PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / tegl_c.exe / TEGLDOC.ZIP / TEGLDISK.PRN < prev next >

Wrap

Text File | 1990-06-28 | 489.9 KB | 15,923 lines

TEGL Windows Toolkit II Release 1.10 Programmer's Reference Guide Copyright (C) 1990, TEGL Systems Corporation All rights reserved TEGL Systems Corporation Suite 780, 789 West Pender Street Vancouver, British Columbia Canada V6C 1H2 TEGL Windows Toolkit II LICENSE AGREEMENT TEGL software products are protected under both Canada copyright law and international treaty provisions. You have the non-exclusive right to use the enclosed software under the following terms and conditions. You may use this software on a single machine, for both personal and business use; and may make copies of the software solely for backup purposes. Other than this you agree to use this software "like a book", meaning the software may be used by any number of people and may be moved from one computer to another so long as there is no possibility of it being used by more than one person at one time. Programs that you write and compile using the TEGL Windows Toolkit may be used, given away, or sold without additional license or fees as long as all copies of such programs bear a copyright notice. By "copyright notice" we mean either your own copyright notice or if you prefer, the following statement, "Created using TEGL Windows Toolkit, copyright (C) 1989, 1990, TEGL Systems Corporation. All rights reserved". Included on the TEGL Windows Toolkit diskettes are a number of support files that contain encoded hardware and font information used by the standard graphic unit. These files are proprietary to TEGL. You may use these files with the programs you create with the TEGL Windows Toolkit for your own personal or business use. To the extent the programs you write and compile using the TEGL Windows Toolkit make use of these support files, you may distribute in combination with such programs, provided you do not use, give away, or sell these support files separately, and all copies of your programs bear a copyright notice. The Complete Games Toolkit diskettes provide a demonstration on how to use the various features of the TEGL Windows Toolkit. They are intended for educational purposes only. TEGL grants you the right to edit or modify these game programs for your own use but you may not give away, sell, repackage, loan, or redistribute them as part of any program, in executable object or source code form. You may, however, incorporate miscellaneous sample program routines into your programs, as long as the resulting programs do no substantially duplicate all or part of a game program in appearance or functionality and all copies of all such programs bear a copyright notice. Limited Warranty: With respect to the physical diskette and physical documentation enclosed herein TEGL warrants same to be free of defects and materials and workmanship for a period of one year from the date of purchase. TEGL will replace defective Software or documentation upon notice within the warranty period of defects. Remedy for breach of this warranty shall be limited to replacement and shall not encompass any other damages, including, without limitation, loss or business profits, business interruption, pecuniary loss, and special incidental, consequential, or other similar claims. This limited warranty is void if failure of the Software has resulted from accident, abuse, or misapplication. Any replacement Software will be warranted for the remainder of the original warrantly period. TEGL specifically disclaims all other warranties, express, implied, or statutory, including but not limited to implied warranties of merchantability and fitness for a particular purpose with respect to the Software and documentation. In no event shall TEGL be liable for any loss of business profit or any other commercial damage including but not limited to special, incidental, consequential, or other damages. Table of Contents TABLE OF CONTENTS SPECIAL NOTE for documentation on disk..................... 13 Acknowledgements........................................... 14 Chapter 1 - Introduction................................... 15 Why Program with TEGL Windows............................ 15 The Components of TEGL Windows Toolkit................... 16 What's On your disks..................................... 16 Installing TEGL on your system........................... 18 Development System Recommendations....................... 19 Compiling with Turbo C................................... 19 Compiling with Quick C................................... 19 How to use this Reference Manual......................... 19 teglsupervisor........................................ 19 Program Framework........................................ 20 Frames or Windows?....................................... 21 How to Contact TEGL Systems Corporation.................. 21 Chapter 2 - TEGL Easy...................................... 23 What TEGL Windows Toolkit can do......................... 23 Event-Driven Code........................................ 23 Attaching your Function to an Event...................... 24 Frames................................................... 25 Menus.................................................... 25 A Minimum TEGL Program................................... 26 Adding Menus (Top Down Design)........................... 27 Adding your First Event.................................. 28 TEGLEasy................................................. 30 activebutton.......................................... 30 coltox................................................ 31 errmess............................................... 31 fitframe.............................................. 32 framefromicon......................................... 32 frametext............................................. 33 getmousey............................................. 34 getyesno.............................................. 35 easytegl.............................................. 36 lastcol............................................... 36 lastrow............................................... 37 outframetextxy........................................ 38 quit.................................................. 38 quickframe............................................ 39 restoretext........................................... 39 rowtoy................................................ 40 selecteasytext........................................ 40 seteasyfont........................................... 41 Chapter 3 - Icons.......................................... 42 The ICON Editor.......................................... 42 The Main Bar Menu..................................... 42 Editing............................................... 42 The Drawing Bar Menu.................................. 42 ICON Constants........................................... 45 Programmer's Reference Guide - 4 - TEGL Windows Toolkit Table of Contents putpict............................................... 45 ICON Assembler Functions................................. 46 ICON Utilities........................................... 46 ICONDEF............................................... 46 ICONLIB............................................... 46 ICONINC............................................... 47 ICONASM............................................... 47 ICONS in TEGLIcon module................................. 47 Chapter 4 - Frames......................................... 49 Creating, Manipulating, and Dropping Frames.............. 49 countframes........................................... 49 frameexist............................................ 49 pushimage............................................. 50 popimage.............................................. 51 rotatestackimage...................................... 52 rotateunderstackimage................................. 53 dropstackimage........................................ 54 hideimage............................................. 56 showimage............................................. 57 showcoordinates....................................... 58 Preparing a Frame for Update............................. 58 prepareforpartialupdate............................... 58 prepareforupdate...................................... 60 commitupdate.......................................... 61 Moving a Frame........................................... 62 frameselectandmove.................................... 63 setautorotate......................................... 64 setmoverestrictions................................... 65 setframemobility...................................... 66 setmoveframecallproc.................................. 67 movestackimage........................................ 68 moveframe............................................. 70 Low Level Frame Functions................................ 70 unlinkfs.............................................. 70 linkfs................................................ 72 linkunderfs........................................... 73 createimagebuffer..................................... 74 dropimagebuffer....................................... 75 getfsimage............................................ 76 putfsimage............................................ 76 freeimagebuffer....................................... 77 getpartialfrontimage.................................. 78 getfrontimage......................................... 78 pageinfs.............................................. 79 lockimage............................................. 79 pageoutfs............................................. 80 setimagecoordinates................................... 81 pageoutimagestack..................................... 81 unlockimage........................................... 82 unuseimage............................................ 82 Programmer's Reference Guide - 5 - TEGL Windows Toolkit Table of Contents useimage.............................................. 83 Mouse Click Areas........................................ 84 definemouseclickarea.................................. 84 findmouseclickptr..................................... 85 resetmsclickactive.................................... 87 resetmsclickcallproc.................................. 87 resetmouseclicks...................................... 88 resetmsclicksense..................................... 89 Keyboard................................................. 90 clearkeyboardbuf...................................... 90 clearteglkeyboardbuf.................................. 90 defineglobalkeyclickarea.............................. 91 definelocalkeyclickarea............................... 92 dropkeyclick.......................................... 92 findkeyclickptr....................................... 93 resetkeyclickcallproc................................. 93 Chapter 5 - Menus.......................................... 94 Creating a Menu.......................................... 94 Creating a entry text list............................... 94 createoptionmenu...................................... 96 defineoptions......................................... 97 createshadowom........................................ 98 resizeoptionmenu...................................... 99 togglecheckmark.......................................100 toggleentrystatus.....................................101 replaceoptiontext.....................................102 toggleoptionbar.......................................103 setoptionmenucolors...................................103 setoptionmenubordercolor..............................104 sethidesubmenu........................................104 Creating a Bar Menu......................................105 createbarmenu.........................................105 outbaroption..........................................106 setbartextcolor.......................................107 setbarmenucolor.......................................107 setbarbordercolor.....................................108 setbarborderoff.......................................108 setbarshadowtext......................................108 setbarfillstyle.......................................109 setbarmenumargin......................................109 Icon Option Menus........................................110 defineoptionclickarea.................................110 resetoptionmenuevents.................................111 Chapter 6 - Mouse, Keyboard and Timer Handlers.............113 Interrupts...............................................113 swapteglintroff.......................................113 swapteglintron........................................114 Mouse Emulation..........................................114 mcursoroff............................................114 mcursoron.............................................115 Programmer's Reference Guide - 6 - TEGL Windows Toolkit Table of Contents msetpos...............................................115 Standard Mouse Functions.................................116 showmouse.............................................116 hidemouse.............................................116 setmouseposition......................................116 cursorshape...........................................117 setmousehotspot.......................................119 setmousecolor.........................................119 mouseposition.........................................119 getbuttonreleaseinfo..................................120 getbuttonpressinfo....................................121 clearbuttoninfo.......................................121 setmouseminmax........................................122 frozenmouse...........................................122 freezemouse...........................................123 unfreezemouse.........................................124 setmousesensitivity...................................124 getmousesensitivity...................................125 setkeyboardmouse......................................125 setkbsteps............................................126 getkbsteps............................................127 Timer Functions..........................................127 swaptimerout..........................................127 swaptimerin...........................................128 settimerstart.........................................128 resettimerflag........................................129 droptimercount........................................129 timerswtich...........................................129 Keyboard Interrupt Events................................130 Keyboard Scan Codes......................................130 addcapturekey.........................................131 deletecapturekey......................................132 teglreadkey...........................................132 teglkeypressed........................................133 nilkeycallproc........................................133 Keyboard Miscellaneous...................................133 setshiftkeys..........................................134 Show Button Status.......................................134 showbuttonstatus......................................134 Chapter 7 - Assembly Language Graphics.....................136 Setting Video Modes......................................136 cga640x200x2..........................................136 ega640x350x16.........................................137 herc720x348x2.........................................137 setvideochoices.......................................138 svga800x600x16........................................138 vga640x480x16.........................................138 videoautodetect.......................................139 videoid...............................................139 Graphic Primitives.......................................140 Programmer's Reference Guide - 7 - TEGL Windows Toolkit Table of Contents fastline..............................................140 putpixs...............................................141 getpixs...............................................141 getbiti...............................................142 putbiti...............................................142 bigimagesize..........................................143 setapage..............................................143 setvpage..............................................144 flipapage.............................................144 flipvpage.............................................145 videopage.............................................145 New Graphic Primitives...................................146 extractpixs...........................................146 extractimg............................................146 overlayimg............................................147 swapbytes.............................................147 Graphic Derivatives......................................147 xorcornerbox..........................................148 xorbox................................................148 Icon Graphics............................................148 putpict...............................................149 pictsize..............................................149 abort_msg.............................................149 Chapter 8 - Special Effects................................151 Screen Backdrop..........................................151 clearteglscreen.......................................151 setteglbordershow.....................................152 setteglbackcolor......................................152 setteglbordercolor....................................153 setteglfillpattern procedure..........................154 setteglfillstyle......................................154 Creating Shadow Boxes....................................155 shadowbox.............................................155 shadowboxtext.........................................156 setshadowcolor........................................156 setshadowbordercolor..................................157 setshadowfillpattern..................................157 setshadowfillstyle....................................158 Creating Shadow Text.....................................159 shadowtext............................................159 setshadowtexttype.....................................160 setshadowtextshadow...................................160 setshadowtexthighlight................................161 shadowtexthighlightoff................................161 Other text effects.......................................162 extendtextxy..........................................162 shifttextxy...........................................162 Buttons..................................................163 definebuttonclick.....................................163 definelongbuttonclick.................................164 Programmer's Reference Guide - 8 - TEGL Windows Toolkit Table of Contents defineuserbuttonclick.................................164 putuserbuttonclick....................................165 Explosions...............................................165 collapsetoiconshow....................................165 collapsetomsclick.....................................166 explodefromiconhide...................................166 explodefrommsclick....................................167 Moving and Transforming XOR Boxes........................167 movebox...............................................167 ziptobox..............................................168 zipfrombox............................................169 Icon Button..............................................170 drawlongbutton........................................170 Chapter 9 - Writing Events.................................171 Mouse Awareness..........................................171 findframe.............................................171 checkmouseclickpos....................................172 checkformouseselect...................................173 Special Effects..........................................174 pressbutton...........................................174 visualbuttonpress.....................................175 Chapter 10 - Animation.....................................177 Animation Overview.......................................177 Animation Functions......................................180 origin procedure......................................180 getorigin.............................................180 destination...........................................181 resetframe............................................182 sequence..............................................182 resetsequence.........................................183 addframe..............................................184 currentframenumber....................................185 animateinit...........................................185 animate...............................................186 animatecomplete.......................................186 Example Animation........................................186 Chapter 11 - Writing Text..................................188 TEGLWrt Variables........................................188 Bit-mapped Fonts.........................................188 Creating Your Own Bit-mapped Fonts.......................188 TEGLWrt Functions and Procedures.........................189 fmttegltextxy.........................................189 outtegltextxy.........................................189 tegltextwidth.........................................190 teglcharwidth.........................................191 teglcharheight........................................191 teglwrtchar...........................................191 setproportional.......................................192 setteglfont...........................................192 Showing ALL Fonts FONTTEST.PAS...........................192 Programmer's Reference Guide - 9 - TEGL Windows Toolkit Table of Contents fontname..............................................193 showonefont...........................................193 showfonts.............................................193 Chapter 12 - Event Library.................................195 The File Selector........................................195 selectafile...........................................195 String Editing Dialog....................................196 editstring............................................196 Mouse Sensitivity Dialogue Window........................196 setmousesense.........................................197 Bells & Whistles, Sound Unit.............................197 asksoundsense.........................................197 beep..................................................198 slidebeep.............................................198 soundswitch...........................................199 Chapter 13 - Virtual Memory Manager........................200 Heap Management..........................................200 The Heap Manager.........................................200 The TEGL Heap Error Function.............................201 The TEGL Heap Manager Functions..........................202 cgetmem...............................................202 cfreemem..............................................203 Expanded Memory Manager (EMM)............................203 Expanded Memory Functions................................204 emminstalled..........................................204 emspagesavailable.....................................205 allocateexpandedmemorypages...........................205 mapexpandedmemorypages................................206 getpageframebaseaddress...............................206 deallocateexpandedmemorypages.........................207 getversionnumber......................................207 gethandlecountused....................................208 getpagesownedbyhandle.................................209 Expanded Memory Test Program.............................209 A RAM Disk Driver........................................212 emsopen...............................................213 emsseek...............................................214 emsblockwrite.........................................214 emsblockread..........................................215 emsclose..............................................216 Virtual Disk Heap........................................216 vdskopenheapfile......................................217 vemsopenheapfile......................................218 vdskgetmem............................................219 vdskfreemem...........................................219 vdskwriteheapdata.....................................220 vdskreadheapdata......................................221 vdskcloseheapfile.....................................221 The Virtual Heap Error Function..........................222 The Virtual Memory Manager...............................222 Programmer's Reference Guide - 10 - TEGL Windows Toolkit Table of Contents useharddisk...........................................223 MoveFromVirtual procedure.............................223 movetovirtual.........................................224 freevirtual...........................................224 cmaxavail.............................................225 virtualmemused........................................225 The Virtual Memory Error Function........................225 Resolving Fragments......................................226 reservehugeminimum....................................227 Chapter 14 - Sizing and Sliders............................228 defineresizeclickarea.................................228 defineresizeminmax....................................229 definesliderarea......................................229 dropsliders...........................................230 findsliderfs..........................................230 resizeframe...........................................231 selectandmoveframe....................................232 setslideposition......................................232 Miscellaneous Functions....................................233 checkctrlbreak........................................233 checkctrlbreakfs......................................233 droptimertick.........................................234 nilunitproc...........................................234 overlaparea...........................................235 settimertick..........................................235 Graphics Library - tgraph..................................237 Bar...................................................237 closegraph............................................238 detectgraph...........................................238 getbkcolor............................................238 getcolor..............................................239 getfillpattern........................................239 getgraphmode..........................................240 getmaxx...............................................240 getmaxy...............................................240 gettextsettings.......................................241 graphresult...........................................241 imagesize.............................................241 initgraph.............................................242 line..................................................242 outtextxy.............................................243 rectangle.............................................243 restorecrtmode........................................243 setbkcolor............................................244 setcolor..............................................244 setfillpattern........................................244 setfillstyle..........................................245 settextjustify........................................245 APPENDICES.................................................246 Video Buffers............................................246 Programmer's Reference Guide - 11 - TEGL Windows Toolkit Table of Contents Windows..................................................246 Frames...................................................246 A Frame Stack............................................247 A Simple Window Manager..................................247 Partial Image Update.....................................249 Refined Partial Image Update.............................249 A Refined Partial Image Update Algorithm.................250 A Quick Run through the algorithm........................252 TEGL Heap Manager........................................254 TEGL Upper Heap Manager..................................258 Combining the best of both Heap Managers (Coexisting)....260 Conditional Compilation..................................263 INDEX......................................................264 Programmer's Reference Guide - 12 - TEGL Windows Toolkit Table of Contents SPECIAL NOTE for documentation on disk You have received Version II of the TEGL Windows Toolkit for TURBO C. The documentation that you are reading is supplied on disk. We will have a printed manual in the near future and it will be somewhat different that what you are looking at now. Because we wanted everyone to be able to read this manual and be able to print it out we have not embedded any special control characters in it with the exception of formfeeds at page breaks. In this manual you will notice that at times there are references to things like ctrlkey or keydown or something discriptive but somewhat odd. Please, be imaginative, these will be icons when the manual is printed. Programmer's Reference Guide - 13 - TEGL Windows Toolkit Acknowledgements Acknowledgements ___________________________________________________________________________ In this manual references are made to several products TURBO C and TURBO Assembler are registered trademarks of Borland International. IBM is a registered trademarks of International Business Machines Inc. MS-DOS and Windows are registered trademarks of Microsoft Inc. MacIntosh is a registered trademark of Apple Computer Inc. Programmer's Reference Guide - 14 - TEGL Windows Toolkit Chapter 1 - Introduction INTRODUCTION ___________________________________________________________________________ Welcome to the world of GUI (Graphical User Interface) in a DOS environment. This guide will provide you with the basics (and more) for getting started with using the TEGL Windows Toolkit. TEGL Windows is a comprehensive GUI toolkit for the simplest to the most sophisticated system programming projects. In order to exploit all the advantages of this toolkit, we encourage you to experiment and to try the examples as listed in this manual. Spending time learning the functions of TEGL Windows will reward you many times over with a system that provides a Professional look and feel. The power of TEGL Windows is limited only by your imagination. Why Program with TEGL Windows Because TEGL Windows Toolkit provides the framework in making programs easy to use. In this way, it is similar to several other user interfaces on the market today, including Apple's Macintosh, Microsoft's Windows and GEM from Digital Research Incorporated. Programs made with TEGL Windows are easier to use for several reasons, visual effects of graphics can generally communicate information more effectively than text. For example, the graphical image of a folder suggests that it contains documents, drawings, and even other folders. Provided are powerful functions that you can use to build very interactive applications. By q very interactive, we mean a type of user interface where a significant portion of the design and development effort goes into making the program easy to use. TEGL Windows Toolkit is based on event handling. Events consists of anything from a key getting pressed on the keyboard, to a timer signaling that some amount of time has elapsed, to a message indicating that the user has selected a particular item from the menu or has selected an icon. A particularly useful capability of this is that while the TEGLSupervisor is waiting for one of these events to occur, you can set the timer to signal a background task like an internal print spooler. This limited multitasking capability makes it easier to build very interactive programs. It's important to note that the TEGL Windows Toolkit supports only a single application running at any given time. Microsoft's Windows will support multiple concurrent applications, provided they are q well-behaved, which means that they don't directly manipulate the computer's hardware. Most popular applications, by the way, are not well-behaved. Programmer's Reference Guide - 15 - TEGL Windows Toolkit Chapter 1 - Introduction TEGL is for a single application, which has the beneficial effect of being part of the final application code and, on the average, much faster than programs written for Windows or GEM. TEGL also takes less RAM, requiring only 50k when all features are used. The Components of TEGL Windows Toolkit Now that you have a rough idea of what the TEGL Windows Toolkit is and how it relates to other alternatives in the microcomputer software marketplace, let's explore its' components n more detail. The purpose of this section is to give you an overall understanding of how to use the toolkit in your program. TEGL is subdivided into a set of libraries; multitasking kernel; windowing screen manager; mouse, keyboard and timer handler; a virtual heap manager; drop down and pop-up menu events; and an animation unit. One of the original goals of TEGL was to provide a graphical user interface (GUI) to a computer running under DOS. This interface is used in a number of entertainment products produced by TEGL Systems Corporation (TSC). As TSC designed and built the entertainment products, TEGL was created to build a set of software routines that were needed by the games. TSC gathered these routines into modules, each categorized by their overall function. For instance, all the routines that manipulate windows are collected and form the TEGLUnit. Similarly, all the drop-down menus and menu bars form TEGLMenu. TEGL Windows Toolkit is the tools that were developed in writing these first entertainment applications. These tools are now available for developing any application The modules are categorized by the kind of functions they deliver; TEGLintr handles the mouse, keyboard and timer interrupts; TEGLMenu provides drop down menus and menu bars; Animate provides icon animation; and VIRTMem provides the virtual heap for almost unlimited windowing ability. TEGLUnit provides a high level integration between window frames, mouse click areas, keyboard handler, timer interrupts, virtual memory, and multitasking kernel. What's On your disks For your reference, here's a summary of most of the files on the distribution disks: README.TXT This file contains any last-minute notes and corrections, type README at the system prompt to Programmer's Reference Guide - 16 - TEGL Windows Toolkit Chapter 1 - Introduction view the file. You may print this file on your printer for future reference, once you review the material. TEGLSYS.H, TEGLSYS.LIB The header file and library for the toolkit. This is all you need to start programming. TEGLUNIT.C This is the window manager that provides the graphical interface support for the other modules. This module provides the event supervisor and the frame/stack coordinator. TEGLMENU.C This unit provides the drop down menu interface. TEGLGRPH.C Module that provides shadow boxes, shadow texts, exploding and imploding boxes, pop-down/pop-up icon buttons, etc.. TEGLICON.C A library of standard icons; key OK, key CANCEL, key NEXT, key LAST. TEGLINTR.C MOUSEASM.ASM Integration of keyboard and mouse handler. This unit provides the standard mouse routines which integrates the keyboard cursor keys and the mouse to provide a seamless dual control of the mouse cursor; with or without a mouse driver. FASTGRPH.C EGAGRAPH.ASM Fast assembly language graphics routines. This is the core of the graphical routines that provide the foundation for pop-down menus and movable windows. This module includes functions that interface with the ANIMATE unit, to allow the recognition of video paging. TEGLWRT.C WRTASM.ASM Crisp proportional Bit-Mapped screen fonts, ranging from 6 to 24 pixels in height. VIRTMEM.C FREEOPEN.ASM Virtual Memory handler that interfaces with TEGLUNIT. This unit automatically pages out images from memory to EMS, hard disk, or floppy (depending on availability), when memory is at a premium. SELECTFL.C Programmer's Reference Guide - 17 - TEGL Windows Toolkit Chapter 1 - Introduction A standard event unit that may be used by any application program to provide a dialogue window in selecting filenames from a list of file on disk. SENSEMS.C A standard event unit that provides a dialogue window that allows a user to adjust the sensitivity of a mouse. SOUNDUNT.C A standard event unit that allows a user to adjust the duration and the sound output of a tone. ANIMATE.C Unit that allows icons to be animated. TEGL.C, TEGL.PRJ A demonstration program that uses most of the features of the TEGL Windows Toolkit II. FONTTEST.C A demonstration event unit that displays all available fonts in movable windows. Used in tegl.pas (sample program). DEBUGUNT.C A demonstration event unit that displays general information regarding windows and the number of times the mouse button has been pressed. FONTASM.ZIP A library of bitmapped fonts in Turbo Assembler format. The source may be modified to create a new font. ICONEDIT.C, ICON*.* The Icon Editor, written using the TEGL Window Toolkit, to design and generate icons to include in your TEGL application. ICONASM, ICONDEF, ICONINC and ICONLIB are standalone programs that will assist you in generating various formats that you can use to add icons to your program. A number of standard icons have been created to include immediately into your application. SAM*.C, SAM*.PRJ Some of the sample programs in this guide are provided in ready-to-compile form. MAKEFILE.MAK The make file for compiling the library. Installing TEGL on your system The complete TEGL Toolkit is approximately 3 megabytes of source code, when expanded. A hard disk is required for the installation. It may be possible to compile on floppy, but we haven't tried it. Programmer's Reference Guide - 18 - TEGL Windows Toolkit Chapter 1 - Introduction At the DOS prompt, type INSTALL, and follow the instructions. Development System Recommendations You must have 640k RAM, a hard disk drive, and an EGA/VGA graphics card with 256k memory and EGA/VGA color monitor on an IBM PC or compatible computer. In our development, we've used an IBM PC AT with 2.5MB RAM, 72MB hard disk, and a paradise VGA 256k card with a NEC/MultiSync 3D. We've also tested all our examples on an IBM PC XT with 640k RAM, a 20MB hard disk, and a ATI VIP VGA graphics adapter card with an IBM 8513 VGA color monitor. Compiling with Turbo C TEGL Windows Toolkit requires Borland's Turbo C Version 2.0, and Turbo Assembler to compile all the units. Turbo Assembler is only needed if you make the library (which is not necessary). Only Turbo C is required to compile programs. Refer to the Turbo C Reference Manual for including headers and using libraries within programs, as well as setting up the environment and creating project files. Compiling with Quick C TEGL Windows Toolkit requires Microsoft Quick C Version 2.0. The graphics functions provided in graphics.lib can be used. See the Appendix Conditional Compilation to best determine your requirements. How to use this Reference Manual This manual is organized in a presentation manner to lead you through the concepts of the TEGL Windows Toolkit II. Each Function is shown seperately with its name, parameter list, and other references. All functions are prototyped in "teglsys.h". For a start here is the main entry point into the TEGL Windows Toolkit II. ___________________________________________________________________________ teglsupervisor ___________________________________________________________________________ Function Main entry point. Syntax Programmer's Reference Guide - 19 - TEGL Windows Toolkit Chapter 1 - Introduction void teglsupervisor(void); Remarks This should be the last statement in main. Example void main() { /* all the setup code for menus etc. goes first */ teglsupervisor(); } Program Framework Most of the examples presented throughout this manual will require the following minimal skeletal C framework before the example code will compile and execute. A few of the examples given are complete programs. /* samshell.c */ /* the minimum requirements for a program */ /* using TEGL Windows Toolkit II */ #include <graphics.h> #include "teglsys.h" void main() { easytegl(); /* insert your code here */ /* then turn control over to the supervisor */ /* use cntrl-break to exit a program that */ /* doesn't have a specific break out point. */ teglsupervisor(); } Programmer's Reference Guide - 20 - TEGL Windows Toolkit Chapter 1 - Introduction Once control has been turned over to the supervisor then the only way to exit a program is by a menu selection or icon that halts the program. Many of the example programs don't have this so you must press Ctrl-Break to exit. When Ctrl-Break is pressed then program control is turned over to an Event Handler. In the case of the sample programs control is passed to quit in tegleasy. An Event Handler, as covered in Chapter 4, is usually attached to an icon, menu selection, or in this case the Ctrl-Break handler. The Ctrl-Break handler, when attached to an exit event, allows the program to exit gracefully by pressing ctrlkey scrlock which is the break key on most keyboards. Chapter 2 provides a foundation to using the TEGL Windows Toolkit by using a few program examples. Chapter 3 shows you how to create an icon using the icon editor, and how to integrate and use the icons in your program. Chapter 4 is heart of the windowing system, which uses most of the functions provided by the other modules. In Chapter 5 we delve further into how the teglmenu works along with teglunit to provide the standard drop-down menus and exploding windows. In Chapters 6 through 8, we discuss some of the graphic and mouse primitives that the teglunit uses. You may use some of these routines independently of TEGL Windows Toolkit. In Chapter 10 we explore animate along with a sample application that animates a button icon. Chapter 11 looks at writing text to a window using bit-mapped fonts. Chapter 12 provides an overview of the standard event library like selecting a file and setting the mouse sensitivity. In Chapter 13, we look at the Virtual Memory handler and how to use VM within an application. Finally, in Chapter 14 and 15, we look at re-sizing, slider bars and anything else that we may have missed. Appendices provide greater details on the TEGL Windows Toolkit and the philosophy behind the design. Frames or Windows? In this manual the word frame is used often. A frame is our term for the implementation of a window. All the identifiers in the toolkit use frame, not window. You can use these terms interchangeably. How to Contact TEGL Systems Corporation If you have any comments or suggestions, you may contact us by writing to TEGL Systems Corporation 780 - 789 West Pender Street Vancouver, British Columbia Canada, V6C 1H2 or phone us at Programmer's Reference Guide - 21 - TEGL Windows Toolkit Chapter 1 - Introduction (604) 669-2577 or facsimile us at (604) 688-9530 Programmer's Reference Guide - 22 - TEGL Windows Toolkit Chapter 2 - TEGL Easy TEGL Easy ___________________________________________________________________________ The TEGL Windows Toolkit provides tools to assist you in creating an eye-appealing, functional and intuitive graphical interface to your programs. There is no fixed format that you must follow when using the TEGL Windows Toolkit. Screen handling, menus, or push button icons are a function of your program design and not a mandatory function of the TEGL Windows Toolkit. However, the tools are provided so you can use emulate the look and feel of most popular windowing packages without locking you into a ridged menu system. What TEGL Windows Toolkit can do Overlapping windows are handled without having the application program redraw the window whenever that window is uncovered. This removes the complexity of having to redraw, which is necessary with some windowing systems. The only time a window has to be redrawn is when it is re-sized. The overhead in maintaining graphic images in memory is offset by the virtual memory manager which automatically swaps the images to EMS and/or disk when more memory is needed. Even with memory swapping, application programs are faster and smaller than those written for other windowing environments. TEGL Windows handles all mouse and keyboard activities, including all selections of a menu items and clicks on a mouse click area. When the user wants to move a window for instance, the teglsupervisor handles all of the user interaction from the clicks of the right mouse button on a window to when the button is released to indicate the new position. When the button is released, and moveframecallproc has been installed for that window, the teglupervisor will call your application procedure with the new location. Your application can either move the frame by calling movestackimage or not do so, depending on whatever it determines is appropriate. Event-Driven Code While it is possible to write your application in a serial manner using TEGL Windows by polling the keyboard to see if a key has been pressed, or checking the mouse if the mouse has been clicked on an icon or menu, it is much more efficient to write using Event-Driven programming. Event-driven programming is a style of building programs that makes for extremely interactive applications. An event is simply the automatic calling of one of your application's functions that is triggered by an action such as the mouse cursor Programmer's Reference Guide - 23 - TEGL Windows Toolkit Chapter 2 - TEGL Easy overlapping with an icon on the screen. This type of event handling removes the complex checking of keyboards and mouse devices from the central program and allows for an almost parallel (multitasking) type of program to be created. Your choice in programming will determine whether your program responds to the user in a sequential mode where one action must be completed before proceeding to the next, or multiple activities that may be completed at the user's leisure. A good example of multiple event handling is a program that simulates a calculator. Each key of the calculator pad is tied together with a Mouse Click Area event-handler (ie. a C function) that handles that particular key. With the selection of one of the numeric icon keys, the supervisor activates the appropriate event-handler which either adds, multiplies, subtracts, or divides the digits. On completion of the event-handler's task, the control is returned back to the supervisor to await for other events. Other event-handlers, such as notepads, will continue to respond to keyboard or mouse actions along with the activities on the calculator. An Event is a powerful concept. Hypertext on the MacIntosh is based on a similar structure. By associating an event with a word, image, or icon, you can chain a series of events together. One event may lead to another? The number of icon/events that can be created is limited only by available memory. Attaching your Function to an Event There are six (6) basic types of events that the teglsupervisor recognizes. The following will provide a brief discussion on event handling. {bo Mouse Click Area} This event occurs whenever the mouse cursor overlaps a defined mouse click area on the screen. Depending on the activation sense, the supervisor may call the event-handler only if the left button is clicked (activation sense set to msclick), or if the mouse cursor passes over the defined mouse click area (activation sense set to mssense). The most common use of a mouse click area is the association of an icon with an event-handler. {bo Click and Drag} This event is associated with the movement of a window. Control is passed Programmer's Reference Guide - 24 - TEGL Windows Toolkit Chapter 2 - TEGL Easy to the Event-handler after a new frame position has been selected. One use of this type of event processing is the dragging of an icon-frame to the trash can (like the MacIntosh). {bo Expand and Shrink} This event is associated with the sizing of a window. Control is passed to the Event-handler after a new frame size has been selected. We use this type of event to re-size a window. {bo Keyboard Events} To accommodate systems without a mouse. The Keyboard Event allows you to tie the keyboard to any normal mouse-click-area event handler. {bo Timer Ticks} The PC has an internal timer that interrupts the activities of any running program 18 times a second. This interruption is transparent to the operating system and is used mainly to update the system clock. The TEGLunit module uses this timer to provide a flag for the interval of timed events. An event-handler may be defined to occur at resolutions up to 18 times a second or several hours later. {bo Ctrl-Break} The Ctrl-Break event is usually tied with the event-handler quit, but, like any Event, you may write your own to perform a a different task when a Ctrl-Break event occurs. Frames TEGL Windows Toolkit is a window manager or more correctly a FRAME STACK coordinator. A frame is any defined region of the screen. By stacking two or more frames on the screen, the supervisor monitors the location of the frames and ensures that each frame retains it's own entity. Once a frame is created, the frame area can be cleared and drawn with any graphic functions provided by the Turbo C language or any other graphical functions provided by other library packages. However, the responsibility of drawing within the window is with the program. Use the x, y, x1, y1 coordinates provided within the frame struct when drawing to the window. Menus Programmer's Reference Guide - 25 - TEGL Windows Toolkit Chapter 2 - TEGL Easy The TEGL Menus are actually event-handlers that have been written to accommodate drop-down menus, menu selections, lists within a frame, etc. The menus require a list of items and related events to be created. The list may then be attached to a bar menu using the OutBarOption, which is simply a frame with multiple horizontal mouse click defines. When teglsupervisor senses the mouse overlapping with one of the bar menu selections, an internal baroptionmenu event is called and a search is made to find the list that is related to the selection. A menu window is then created and displayed using the list. The menu window is simply another frame with multiple mouse click defines. A Minimum TEGL Program The following demo program, prints out the message q Hello World! to a small movable window. Note: this one doesn't require the minimum shell that we described in the Introduction. /* samc0201.c */ /* the minimum requirements for a program */ /* using TEGL Windows Toolkit II */ #include <graphics.h> #include "teglsys.h" void main() { easytegl(); /* insert your code here */ pushimage(100,100,200,120); shadowbox(100,100,200,120); setcolor(BLACK); outtegltextxy(105,105,"Hello world"); /* then turn control over to supervisor */ teglsupervisor(); } Programmer's Reference Guide - 26 - TEGL Windows Toolkit Chapter 2 - TEGL Easy Adding Menus (Top Down Design) A powerful feature in programming with TEGL Windows is the ability to visually see your application develop. Top down design is a methodology where the layout and menu designs are created first and the functional aspect of the program created later. Program stubs are used as place markers to indicate the required function. Adding a drop down menu and connecting the event later is a simple task with TEGL Windows. /* samc0202.c */ #include <graphics.h> #include "teglsys.h" optionmptr om1, om2; unsigned getmssense(imagestkptr ifs, msclickptr ms) { setmousesense(ifs->x,ifs->y); return(1); } void main() { easytegl(); om1 = createoptionmenu(font14); defineoptions(om1," Info... ",TRUE,NULL); defineoptions(om1,"--", FALSE, NULL); defineoptions(om1," Quit ", TRUE, quit); om2 = createoptionmenu(font14); defineoptions(om2," Memory ",TRUE,showcoordinates); defineoptions(om2," Mouse sensitivity ",TRUE,getmssense); createbarmenu(0,0,getmaxx()); outbaroption(" File ",om1); outbaroption(" Utility ",om2); teglsupervisor(); } Programmer's Reference Guide - 27 - TEGL Windows Toolkit Chapter 2 - TEGL Easy The event showcoordinates is defined as part of the DebugUnt module, setmousesense is defined in SENSEMS, and Quit is defined in TEGLEasy. Info... is defined to NULL which is a program event stub that does nothing. Adding events as you go along is easy, now that the menu is set up. Adding your First Event The following is an event that opens a window and writes a message. Notice how we attached infooption as an event to the menu selection Info... by replacing NULL with infooption. /* samc0203.c */ #include <graphics.h> #include "teglsys.h" optionmptr om1, om2; unsigned infooption(imagestkptr ifs, msclickptr ms) { imagestkptr fs; unsigned x=200,y=120,w=340,h=100; hidemouse(); quickframe(&fs,&x,&y,&w,&h); setcolor(BLACK); frametext(fs,1,2,"TEGL Windows Toolkit II"); frametext(fs,2,2,"Copyright 1990, TEGL Systems Corporation"); frametext(fs,3,2,"All Rights Reserved."); showmouse(); return(1); } unsigned getmssense(imagestkptr ifs, msclickptr ms) { setmousesense(ifs->x,ifs->y); return(1); Programmer's Reference Guide - 28 - TEGL Windows Toolkit Chapter 2 - TEGL Easy } void main() { easytegl(); om1 = createoptionmenu(font14); defineoptions(om1," Info... ",TRUE,infooption); defineoptions(om1,"--", FALSE, NULL); defineoptions(om1," Quit ", TRUE, quit); om2 = createoptionmenu(font14); defineoptions(om2," Memory ",TRUE,showcoordinates); defineoptions(om2," Mouse sensitivity ",TRUE,getmssense); createbarmenu(0,0,getmaxx()); outbaroption(" File ",om1); outbaroption(" Utility ",om2); teglsupervisor(); } You may notice that the event returns to the TEGLSupervisor leaving the window on the screen. We can refined this procedure by adding a while loop to wait for the user to click on a icon. The getmousey(ifs) function will return once the user has selected the OK icon. The new event listing. unsigned infooption(imagestkptr ifs, msclickptr ms) { imagestkptr fs; unsigned x=200,y=120,w=340,h=100; hidemouse(); quickframe(&fs,&x,&y,&w,&h); setcolor(BLACK); frametext(fs,1,2,"TEGL Windows Toolkit II"); frametext(fs,2,2,"Copyright 1990, TEGL Systems Corporation"); frametext(fs,3,2,"All Rights Reserved."); Programmer's Reference Guide - 29 - TEGL Windows Toolkit Chapter 2 - TEGL Easy definebuttonclick(fs,x+300,y+70,imageOK,NULL); getmousey(fs); dropstackimage(fs); showmouse(); return(1); } TEGLEasy ___________________________________________________________________________ activebutton ___________________________________________________________________________ Function Makes a button/frame. Syntax void activebutton(unsigned x, unsiged y, char *s, callproc ); Remarks This is for creating a button which is attached to a frame that is the same size as the button. p the event can then have as the first statement framefromicon to make a dramatic button to frame transition. Restrictions if the imagestkptr is required then save the stackptr immediately after calling activebutton. See also explodefromiconhide, collapsetoiconshow. Example activebutton(100,100,"INFO",infooption); ___________________________________________________________________________ coltox Programmer's Reference Guide - 30 - TEGL Windows Toolkit Chapter 2 - TEGL Easy ___________________________________________________________________________ Function Calculates the X coordinate for a text col. Syntax int coltox(int col); Remarks This is used to treat the graphics display as if it were in text mode to make it easy to place a succession of characters. Restrictions The calculation is made using the currently selected font. See also rowtoy, setteglfont, seteasyfont. Example outtegltextxy(coltox(col)+ifs->x,rowtoy(row)+ifs->y,s); ___________________________________________________________________________ errmess ___________________________________________________________________________ Function Display an error message. Syntax void errmess(unsigned x, unsigned y,char *s); Remarks The error message s is displayed in a frame at coordinates x,y. The frame is sized to the message and is adjusted to keep within the confines of the screen. The frame is displayed until the 'OK' button in the lower right corner is clicked. See also getyesno. Example errmess(100,100,"You must enter a file name first"); Programmer's Reference Guide - 31 - TEGL Windows Toolkit Chapter 2 - TEGL Easy ___________________________________________________________________________ fitframe ___________________________________________________________________________ Function Creates coordinates that fit on the physical screen. Syntax void FitFrame(unsigned *x, unsigned *y, unsigned *width, unsigned *height); Remarks x,y are the desired upper left coordinates for a frame. width and height are the desired width and height in pixels for the frame. If the starting coordinates would cause the frame to extend beyond the bounds of the screen then they are decremented until the frame will fit. If width or height are greater than their corresponding getmaxx or getmaxy then they are set to the maximum screen size. The lower right coordinates are returned in width=x1, and height=y1. See also quickframe. Example unsigned x=639,y=120,w=340,h=100; fitframe(x,y,w,h); /* adjusted to x=299 */ ___________________________________________________________________________ framefromicon ___________________________________________________________________________ Function Opens a frame in an event that was called from a click on a icon. Syntax Programmer's Reference Guide - 32 - TEGL Windows Toolkit Chapter 2 - TEGL Easy void framefromicon(imagestkptr ifs, msclickptr ms, unsigned x, unsigned y, unsigned x1, unsigned y1); Remarks This would be the first statement in an event that is attached to an icon or button created with active button. This procedure will hide the icon then display an exploding wire box from the icon location to the coordinates x,y,x1,y1 where a frame is opened and cleared. An OK button is placed in the lower right corner of the frame and it is attached to collapsetoiconshow which will close the frame when it is clicked on. See also activebutton, explodefromiconhide Example /* samc0205.c */ #include "teglsys.h" unsigned easymessage(imagestkptr frame,msclickptr mouseclickpos) { framefromicon(frame,mouseclickpos,150,150,400,190); prepareforupdate(stackptr); frametext(stackptr,1,2,"Icon to Frame Transformation"); commitupdate(); return 1; } void main() { easytegl(); activebutton(100,100,"MESSAGE",easymessage); teglsupervisor(); } ___________________________________________________________________________ frametext ___________________________________________________________________________ Programmer's Reference Guide - 33 - TEGL Windows Toolkit Chapter 2 - TEGL Easy Function Writes text to a frame using row, column coordinates simulating text mode. Syntax void frametext(imagestkptr ifs, int row, int col, char *s); Remarks ifs is the frame to write to. Row and Col are the row and column locations relative to the frame. That is, row 1, col 1, is the upper left corner of the frame. Note the coordinates are the reverse of graphics coordinates where column comes first. Restrictions The text display is based upon the current font. Swithing fonts will cause uneven text. Example /* samc0206.c */ #include "teglsys.h" void main() { imagestkptr fs; unsigned x=100,y=100,w=200,h=50; easytegl(); quickframe(&fs,&x,&y,&w,&h); frametext(fs,2,2,"Hello World!"); teglsupervisor(); } ___________________________________________________________________________ getmousey ___________________________________________________________________________ Function Waits for a mouse click and returns the mouse click number. Syntax unsigned getmousey(imagestkptr ifs) Programmer's Reference Guide - 34 - TEGL Windows Toolkit Chapter 2 - TEGL Easy Remarks Mouse clicks numbers are numbered in the order that you define the mouse click areas. ifs is the frame where we are waiting for a mouse click to occur. The mouse click number is returned. Example definebuttonclick(fs,x+250,y+70,imageOK,NULL); definebuttonclick(fs,x+300,y+70,imageCANCEL,NULL); switch (getmousey(fs)) { case 1 : /* imageOK was clicked on */ break; case 2 : /* imageCANCEL was clicked on */ break; } ___________________________________________________________________________ getyesno ___________________________________________________________________________ Function Gets a yes or no response. Syntax char getyesno(unsigned x,unsigned y, char *s); Remarks x,y are the coordinates to display the frame. s is the question to ask, allowing that the only answer can be Yes or No. The frame has a yes and no button displayed in the lower right corner. This function returns a 1 if Yes is clicked and 0 if No is clicked. Example if (getyesno(100,100,'Do you want to erase the file')) { /* erase the file */ } else ; /* cancel the command */ Programmer's Reference Guide - 35 - TEGL Windows Toolkit Chapter 2 - TEGL Easy ___________________________________________________________________________ easytegl ___________________________________________________________________________ Function Does a simplified startup for the toolkit. Syntax void easytegl(void); Remarks This procedure should be called at the very start of your program. It sets up some default values and clears the screen. When you have become familiar with the start-up requirements of the TEGL Windows Toolkit then you can write your own initialization procedure. Example #include "teglsys.h" void main() { easytegl(); teglsupervisor(); } ___________________________________________________________________________ lastcol ___________________________________________________________________________ Function Returns the number or last column of a frame calculated by the number of text characters that will fit within a frame. Syntax int lastcol(imagestkptr ifs); Remarks The calculation is based upon the currently selected font. Programmer's Reference Guide - 36 - TEGL Windows Toolkit Chapter 2 - TEGL Easy Restrictions Does not allow for BGI fonts. See also lastrow, coltox, rowtoy. Example imagestkptr fs; unsigned x=100,y=100,w=200,h=50; lastcol(fs); /* returns the number of columns that will fit */ ___________________________________________________________________________ lastrow ___________________________________________________________________________ Function Returns the number or last row of a frame calculated by the number of text characters rows that will fit within a frame. Syntax int lastrow(imagestkptr ifs); Remarks The calculation is based upon the currently selected font. Restrictions Does not allow for BGI fonts. See also lastcol, coltox, rowtoy. Example imagestkptr fs; unsigned x=100,y=100,w=200,h=50; lastrow(fs); /* returns the number of rows that will fit */ ___________________________________________________________________________ outframetextxy Programmer's Reference Guide - 37 - TEGL Windows Toolkit Chapter 2 - TEGL Easy ___________________________________________________________________________ Function Writes text to frame using relative coordinates. Syntax void outframetextxy(imagestkptr ifs, unsigned x, unsigned y, char *s); Remarks Macro Uses the currently selected font. Normally, outtegltextxy(..) uses screencoordinates to display your graphic text. Thus you are required to add ifs->x and ifs->y to your offsets. outframetextxy expands to add the frame coordinates to your relative coordinates. Restrictions Does not work with BGI fonts. See also frametext. Example /* writes "message" at x=5,y=5 pixels from the upper left corner of fs */ outframetextxy(fs,5,5,"message"); ___________________________________________________________________________ quit ___________________________________________________________________________ Function Halts program. Syntax unsigned quit(imagestkptr ifs, msclickptr ms); Remarks Control break is set to this event by default in easytegl. setctrlbreakfs(quit); Programmer's Reference Guide - 38 - TEGL Windows Toolkit Chapter 2 - TEGL Easy ___________________________________________________________________________ quickframe ___________________________________________________________________________ Function Pushes an image and clears the frame. Syntax void quickframe(imagestkptr *ifs, unsigned *x, unsigned *y, unsigned *width, unsigned *height); Remarks x,y are the desired upper left coordinates, width and height are the size of the frame. Coordinates are adjusted to fit the physical screen and are returned in x,y,width,height. The frame struc is also returned in ifs. See also fitframe. Example imagestkptr ifs; int x=100,y=100,w=200,h=150; hidemouse(); quickframe(&ifs,&x,&y,&w,&h); frametext(ifs,2,2,"This is too TEGL easy!"); showmouse(); ___________________________________________________________________________ restoretext ___________________________________________________________________________ Function Restores the current font. Syntax Macro void restoretext(void); Remarks Programmer's Reference Guide - 39 - TEGL Windows Toolkit Chapter 2 - TEGL Easy the current font is saved when selecteasytext is called. selecteasytext allows you to temporary change to another font. ___________________________________________________________________________ rowtoy ___________________________________________________________________________ Function Calculates the Y coordinate for a text row. Syntax int rowtoy(int row); Remarks This is used to treat the graphics display as if it were in text mode and make it easier to place succeeding rows of text on the screen. Returns the pixel offset needed to add to frame->y to get row. Restrictions The calculation is based on the current font. See also coltox, lastcol, lastrow, frametext ___________________________________________________________________________ selecteasytext ___________________________________________________________________________ Function Changes to the font set by seteasyfont Syntax Macro void selecteasytext(void); Remarks The font used after this call is selected by previous call to seteasyfont. See also restoretext. ___________________________________________________________________________ seteasyfont Programmer's Reference Guide - 40 - TEGL Windows Toolkit Chapter 2 - TEGL Easy ___________________________________________________________________________ Function Set the font used by the TEGLEasy Unit. Syntax Macro void seteasyfont(fontptr p); Remarks Some of the routines in TEGLEasy write to the screen. This font is used by these routines. See also selecteasytext, restoretext Example seteasyfont(countdwn); Programmer's Reference Guide - 41 - TEGL Windows Toolkit Chapter 3 - Icons ICONS ___________________________________________________________________________ Icons are pictures that represent objects. This Icon image diskdrve represents a diskette. Icons are the mainstay of GUI's. The TEGL Windows Toolkit provides the tools that can create and manipulate icons up to a 100 x 100 pixels in size. By placing an icon within a window frame, they may be attached directly to an TEGL event to provide graphical menu selections, animated to provide visual feedback, displayed as graphic images like the TEGL Deck of Cards, or used to display a company logo. The ICON Editor Included in TEGL Windows Toolkit is a powerful icon editor that utilizes the full power of the tookit to provide you with fast, flexible and easy icon file editing. The source code for the icon editor is also included so you can expand and modify it to suit your needs. The Main Bar Menu Open ICONDEF File Opens an existing ICON.DEF file, or creates a new DEF file. To create a new DEF file, type in the name of the DEF file in the filename box and click on key OK. Quit Quits the icon editor. NOTE: The icon editor does not prompt you to save your files. Editing The mouse cursor changes to cross-hairs when the cursor enters the icon drawing area. Pressing the mouse left button will place a pixel at the current coordinates. Pressing the mouse right button will erase the pixel. You can hold the mouse left or right button, while moving the mouse to draw or erase a series of pixels. The drawing bar at the bottom of the drawing area has two functions. Press and hold the right mouse button on the drawing bar to drag the drawing area to a new location. Click with the left mouse button on the drawing bar to select from the drawing menu. The Drawing Bar Menu SAVE Programmer's Reference Guide - 42 - TEGL Windows Toolkit Chapter 3 - Icons Saves the file with the filename displayed on the drawing bar. SAVE AS Saves the file with a new filename. SAVE AND EXIT ICON FILE Saves the file with the filename displayed on the drawing bar and closes the editing area for the file. CREATE C CONSTANTS Creates a c constant file with the extension q .CON for including in a program. COPY IMAGE AREA Copies an area into the internal IMAGE AREA. When this option is active a scissors icon appears on the drawing bar. Click once with the left mouse button to mark the upper left corner of the area to copy. Move the mouse cursor to the bottom right corner of the area to copy and click again on the left mouse button. When the scissors disappear, the area has been copied to the internal IMAGE AREA. CUT IMAGE AREA Copies an area into an internal IMAGE AREA and clears the Icon area to the background color. When this option is active a scissors icon appears on the drawing bar. Click once with the left mouse button to mark the upper left corner of the area to cut. Move the mouse cursor to the bottom right corner of the area and click again on the left mouse button. When both the scissors disappear and the area is cleared, then the area has been copied to the internal IMAGE AREA. FILL IMAGE AREA Fills an area with the current pixel color. Bits that are already set on are not overwritten. When this option is active, a coffee mug icon appears on the drawing bar. Click once with the left mouse button to mark the upper left corner of the area to fill. Move the mouse cursor to the bottom right corner of the area and click again on the left mouse button. The coffee mug disappears when the area is filled with current pixel color. PASTE IMAGE AREA Paste the copied/cut area from the internal IMAGE AREA to the icon drawing area. When this option is active, a glue bottle icon appears on the drawing bar. Click once at the position where the image is to be pasted. The pasted image overwrites any pixels on the drawing area. Programmer's Reference Guide - 43 - TEGL Windows Toolkit Chapter 3 - Icons MERGE IMAGE AREA Merges the copied/cut area from the internal IMAGE AREA to the icon drawing area. When this option is active, a glue bottle icon appears on the drawing bar. Click once at the position where the image is to be merged. The merged image only writes to empty pixel areas. OVERLAY IMAGE AREA Overlays the copied/cut area from the internal IMAGE AREA to the icon drawing area. When this option is active, a glue bottle icon appears on the drawing bar. Click once at the position where the image is to be overlayed. The overlay image only writes to active pixels. ROTATE IMAGE AREA 45 DEGREES Rotates the internal IMAGE AREA by 45 degrees. ROTATE IMAGE AREA 90 DEGREES Rotates the internal IMAGE AREA by 90 degrees. REDUCE IMAGE AREA Shrinks the image within the internal IMAGE AREA by 50%. The algorithm deletes every second pixel. REVERSE IMAGE AREA Reverses the image within the internal IMAGE AREA from left to right. PIXEL COLOR Pick the current pixel color from a palette of 16 colors. BACKGROUND COLOR Pick the current background color from a palette of 16 colors. CHANGE PIXELS COLOR Change all pixels with color m to another color n. Where m and n are selected from a palette of 16 colors. To cancel the command without changing any pixel colors, select the same color for both m and n. ERASE COLOR PIXELS Erases all pixels with the selected pixel color. The color is selected from a palette of 16 colors. Programmer's Reference Guide - 44 - TEGL Windows Toolkit Chapter 3 - Icons EXPLODE ICON IMAGE Enlarges the drawing area. The largest size is a ratio of 3 to 1 (3 pixels representing 1 pixel). IMPLODE ICON IMAGE Shrinks the drawing area. CLEAR ICON IMAGE Clears the drawing area. RELOAD ICON FILE Reloads the original icon file. EXIT ICON FILE Finishes the editing of a icon file. You can open as many editing windows at once as you like. The internal IMAGE AREA is common to all the edit windows that are open. Consequently, whatever is in the internal IMAGE AREA can be pasted to any edit window. This allows for the building of icons from small pieces, or copying an icon to transform it to something different. ICON Constants Select from the Drawing Bar Menu CREATE C CONSTANTS, to generate constants for including in your program. If you have a large number of icons for generating constants, you can use the program ICONINC to generate all icons in a one pass. ___________________________________________________________________________ putpict ___________________________________________________________________________ Function Puts the defined icon to the specified screen area. Syntax void putpict(unsigned x,unsigned y, unsigned char *buf,unsigned n); Remarks x, y defines the upper left corner of the screen area for placing the icon image. buf points to the defined icon image. n defines the color change for any pixel that is Programmer's Reference Guide - 45 - TEGL Windows Toolkit Chapter 3 - Icons black within the icon. ICON Assembler Functions The program ICONASM provides a second method that allows you to add large icon images to your program (eg. the TEGL Deck of Cards). ICONASM generates a C function in assembler. Turbo Assembler is required to assemble the file to object code. You may then create an obj file that will link the icon function into your C program. To display the icon, use the icon function name (your icon name prefixed with Image). imageMyIcon(10,25,BLACK); Note that these functions are always far. ICON Utilities ICONDEF ICONDEF is a utility program that allows you to strip the .DEF files from a turbo C source file, include file or Assembler file, provided that the commented /*.. prefix is still a part of your constants. Be careful that the Input filename is not the same as one of the definition files. Using a suffix other then .DEF will ensure that the include file is not overwritten while extracting. However, any filenames that do end in .DEF should be copied to a subdirectory if you are not sure about the ICON definition names. Syntax: ICONDEF MYFILE.INC Where: MYFILE.INC is the include file generated by ICONINC or any file that embeds the include file. ICONLIB ICONLIB is for assisting the programmer in combining the definition files into a single library file for maintenance. Use ICONDEF to extract. Programmer's Reference Guide - 46 - TEGL Windows Toolkit Chapter 3 - Icons Syntax: ICONLIB *[.DEF] MYPROG.DLB Where: *[.DEF] may use any DOS wild-card specifications. MYPROG.DLB may be any library filename. ICONINC ICONINC helps the ICON Editor in generating a large number of Turbo C ICON constants. Multiple icon definitions may be output to a single include file. Syntax: ICONDEF *[.DEF] MYFILE.INC Where: *[.DEF] may use any DOS wildcards specifications. MYFILE.INC may be any include filename. ICONASM ICONASM is for assisting the ICON Editor in generating functions from icon definition files. Multiple functions may be output to a single asm file. Syntax: ICONASM *[.DEF] MYPROG.ASM Where: *[.DEF] may use any DOS wildcards specifications. MYPROG.ASM may be any assembler filename. ICONS in TEGLIcon module. There are a number of icons that have been created. The following are included in the "teglsys.h" file. ImageCREDITS TEGL Windows Toolkit II ImageTRASH A trash can ImageOK Programmer's Reference Guide - 47 - TEGL Windows Toolkit Chapter 3 - Icons OK button ImageCANCEL Cancel button ImageBLANKBUT A blank button for creating your own ImageLBUT ImageMBUT ImageRBUT Used by DrawLongButon to create an extra long button icon. ImageDOWN Down arrow. ImageUP Up arrow. ImageRIGHT Right arrow. ImageLEFT Left arrow. ImageR Registered Trademark. reg ImageC Copyright. copyright ImageTIGER A TEGL tiger. ImageLAST Last button. ImageNEXT Next button. ImageQUESTION Question Button. Programmer's Reference Guide - 48 - TEGL Windows Toolkit Chapter 4 - Frames Frames ___________________________________________________________________________ The power and speed of TEGL Windows is most apparent when handling frames. By automatically saving and restoring overlapping images, TEGL Windows is a very powerful tool for creating the illusion of separate multiple windows. Appendix A describes the philosophy behind the TEGL Windows Toolkit. This chapter provides the basic foundation for creating, manipulating, and attaching related items to a frame. Creating, Manipulating, and Dropping Frames ___________________________________________________________________________ countframes ___________________________________________________________________________ Function Returns the number of frames currently on the stack. Syntax unsigned countframes(void); ___________________________________________________________________________ frameexist ___________________________________________________________________________ Function Determines if a frame is on the frame stack. Syntax char frameexist(imagestkptr ifs); Remarks If ifs exists then it contains the address of one of the frames on the stack. Example if frameexist(ifs) dropstackimage(ifs); Programmer's Reference Guide - 49 - TEGL Windows Toolkit Chapter 4 - Frames ___________________________________________________________________________ pushimage ___________________________________________________________________________ Function Used to save the background image before clearing and drawing new images in this area. Equivalent to opening a window area. Syntax void pushimage(unsigned x, unsigned y,unsigned x1, unsigned y1); Remarks Windows are created by pushing and popping the background image. x, y, x1, y1 are absolute coordinates starting with 0,0 at the upper left corner of the screen to getmaxx, getmaxy at the lower right corner. Restrictions Saving large images can require a lot of memory even with the Virtual Memory Manager. If a program is expected to use most of memory it would be sensible to include specific checks on memory requirements and availability before performing a PushImage. A full screen in EGA mode (640 x 350) requires about 110K of memory, in VGA mode (640 x 480) the requiment is about 150K. See also popimage, dropstackimage, rotatestackimage, rotateunderstackimage Example The following will create a shadowed box on the upper left screen area. Use the right mouse button to drag the box around. /* samc0401.c */ #include "teglsys.h" Programmer's Reference Guide - 50 - TEGL Windows Toolkit Chapter 4 - Frames void main() { easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); teglsupervisor(); } ___________________________________________________________________________ popimage ___________________________________________________________________________ Function Used to restore the top background image after a PushImage. Equivalent to closing a window area. Syntax void popimage(void); Remarks Restores the uppermost image area created by (it pushImage. See also pushimage, dropstackimage, rotatestackimage, rotateunderstackimage Example This example waits until a mouse button is pressed then calls popimage to restore the background image. /* samc0402.c */ #include "teglsys.h" void main() { easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); showmouse(); Programmer's Reference Guide - 51 - TEGL Windows Toolkit Chapter 4 - Frames while( mouse_buttons == 0 ); popimage(); while( mouse_buttons == 0 ); abort_msg(""); } ___________________________________________________________________________ rotatestackimage ___________________________________________________________________________ Function Rotates a frame forward or backward relative to the frames on the screen. Syntax void rotatestackimage(imagestkptr frame1, imagestackptr frame2); Remarks Frames may be rotated to the foreground to allow user input or updates, etc. A frame may be rotated as the first frame using rotatestackimage. In order to access an image that is not the most recent pushimage you must save the global variable stackptr right after the pushimage. the saved pointer may be used to manipulate the frame. Restrictions A frame can only be rotated above a known frame. To rotate a frame below another frame on the stack, use the rotateunderstackimage routine. See also pushimage, popimage, dropstackimage Example The following example creates two overlapping frames and waits for a click of a mouse button before rotating the bottom frame to the top. Programmer's Reference Guide - 52 - TEGL Windows Toolkit Chapter 4 - Frames /* samc0403.c */ #include "teglsys.h" void main() { imagestkptr fs; inittegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); showmouse(); while( mouse_buttons == 0 ); rotatestackimage(fs,stackptr); while( mouse_buttons == 0 ); abort_msg(""); } ___________________________________________________________________________ rotateunderstackimage ___________________________________________________________________________ Function Rotates a frame forward or backward relative to the frames on the screen. Rotates a frame below frame2. Syntax void rotateunderstackimage(imagestkptr frame1, imagestkptr frame2); Remarks In order to access an image that is not the most recent pushimage you must save the global variable stackptr right after the pushimage. the saved pointer may be used to manipulate the frame. Programmer's Reference Guide - 53 - TEGL Windows Toolkit Chapter 4 - Frames Restrictions A frame can only be rotated below a known frame. To rotate a frame above another frame on the stack, use the rotatestackimage. See also pushimage, popimage, dropstackimage Example The following example creates two overlapping frames and awaits for a click of a mouse button before rotating the Top frame under the second frame. /* samc0404.c */ #include "teglsys.h" void main() { imagestkptr fs; easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); showmouse(); while( mouse_buttons == 0 ); rotateunderstackimage(stackptr,fs); while( mouse_buttons == 0 ); abort_msg(""); } ___________________________________________________________________________ dropstackimage ___________________________________________________________________________ Programmer's Reference Guide - 54 - TEGL Windows Toolkit Chapter 4 - Frames Function Used to close a frame that is not necessarily the topmost image on the stack. Equivalent to closing a window area. Syntax void dropstackimage(imagestkptr frame); Remarks Restores an image area created by pushimage. In order to access an image that is not the most recent pushimage you must save the global variable stackptr right after the pushimage. The saved pointer may be used to manipulate the frame. See also pushimage, popimage, rotatestackimage, rotateunderstackimage Example The following example creates two overlapping frames and awaits for a click of a mouse button before dropping the bottom frame from the screen. /* samc0405.c */ #include "teglsys.h" void main() { imagestkptr fs; easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); showmouse(); while( mouse_buttons == 0 ); dropstackimage(fs); while( mouse_buttons == 0 ); abort_msg(""); } Programmer's Reference Guide - 55 - TEGL Windows Toolkit Chapter 4 - Frames ___________________________________________________________________________ hideimage ___________________________________________________________________________ Function Hides an Image Frame from the screen but retains the current stack position and frontal image. Syntax void hideimage(imagestkptr frame); Remarks This procedure may be used in a variety of ways. Blinking a frame by alternating between hideimage and showimage. Moving a frame from one location to another. See also showimage Example The following example blinks a frame continuously until a mouse button is pressed. /* samc0406.c */ #include "teglsys.h" void main() { imagestkptr fs; unsigned i; easytegl(); pushimage(1,1,50,50); shadowbox(1,1,50,50); fs = stackptr; showmouse(); i = 20000; do { --i; Programmer's Reference Guide - 56 - TEGL Windows Toolkit Chapter 4 - Frames if (i == 10000) hideimage(fs); if (i == 0) { showimage(fs,fs->x,fs->y); i = 20000; } } while( mouse_buttons == 0 ); if (i <= 10000) showimage(fs,fs->x,fs->y); } ___________________________________________________________________________ showimage ___________________________________________________________________________ Function Shows a Hidden Image Frame. Syntax void hideimage(imagestkptr frame) See also hideimage Example The following example moves a frame from one location to another when a mouse button is pressed. /* samc0407.c */ #include "teglsys.h" void main() { imagestkptr fs; easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs = stackptr; Programmer's Reference Guide - 57 - TEGL Windows Toolkit Chapter 4 - Frames pushimage(50,50,150,150); shadowbox(50,50,150,150); showmouse(); while( mouse_buttons == 0 ); hideimage(fs); showimage(fs,fs->x+100,fs->y+100); while( mouse_buttons == 0 ); abort_msg(""); } ___________________________________________________________________________ showcoordinates ___________________________________________________________________________ Function An Event that displays the coordinates of a frame. Syntax unsigned showcoordinates(imagestkptr ifs, msclickptr ms); Remarks This event displays the coordinates of a frame. Preparing a Frame for Update ___________________________________________________________________________ prepareforpartialupdate ___________________________________________________________________________ Function Prepares a portion of a frame for output. Removes all overlapping images above the partial area that is being updated on the screen. Syntax Programmer's Reference Guide - 58 - TEGL Windows Toolkit Chapter 4 - Frames void prepareforpartialupdate(imagestkptr frame; unsigned x, unsigned y,unsigned x1, unsigned y1); Remarks x,y,x1,y1 are absolute coordinates starting with 0,0 at the upper left corner of the screen to getmaxx, getmaxy at the lower right corner. Restrictions The coordinates must be within the absolute frame coordinates. Use the current Frame coordinates + offsets to obtain the correct absolute coordinates. prepareforpartialupdate and prepareforupdate can be used on multiple frames (provided the update areas do not overlap) but must be matched by an equal number of calls to commitupdate. See also prepareforupdate, commitupdate Example The following example creates two overlapping frames and awaits for a click of a mouse button before drawing a circle on the bottom frame. /* samc0408.c */ #include <graphics.h> #include "teglsys.h" void main() { imagestkptr fs; easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); showmouse(); while( mouse_buttons == 0 ); prepareforpartialupdate(fs,fs->x,fs->y,fs->x1,fs->y1); setcolor(BLUE); circle(fs->x+48,fs->y+45,50); commitupdate(); Programmer's Reference Guide - 59 - TEGL Windows Toolkit Chapter 4 - Frames while( mouse_buttons == 0 ); abort_msg(""); } ___________________________________________________________________________ prepareforupdate ___________________________________________________________________________ Function Prepares a frame for output. Removes all overlapping images above the frame area that is being updated on the screen. Syntax void prepareforupdate(imagestkptr frame); Remarks Identical to prepareforpartialupdate, except the current frame coordinates are passed automatically. Restrictions prepareforpartialupdate and prepareforupdate can be used on multiple frames (provided the update areas do not overlap) but must be matched by an equal number of calls to commitupdate. See also prepareforpartialupdate, commitupdate Example The following example creates two overlapping frames and awaits for a click of a mouse button before drawing a circle on the bottom frame. /* samc0409.c */ #include <graphics.h> #include "teglsys.h" void main() { imagestkptr fs; Programmer's Reference Guide - 60 - TEGL Windows Toolkit Chapter 4 - Frames easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); showmouse(); while( mouse_buttons == 0 ); prepareforupdate(fs); setcolor(BLUE); circle(fs->x+48,fs->y+45,50); commitupdate(); while( mouse_buttons == 0 ); abort_msg(""); } ___________________________________________________________________________ commitupdate ___________________________________________________________________________ Function Commits update. Replaces all overlapping images above the frame area that was being updated on the screen. Syntax void commitupdate(void); Remarks commitupdate must be used to close the functions prepareforpartialupdate and prepareforupdate. Restrictions commitupdate must be called an equal number of times for each prepareforpartialupdate and prepareforupdate. See also Programmer's Reference Guide - 61 - TEGL Windows Toolkit Chapter 4 - Frames prepareforpartialupdate, prepareforupdate Example The following example creates two overlapping frames and awaits for a click of a mouse button before drawing a circle on the bottom frame. /* samc04010.c */ #include <graphics.h> #include "teglsys.h" void main() { imagestkptr fs; easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); showmouse(); while( mouse_buttons == 0 ); prepareforupdate(fs); setcolor(BLUE); circle(fs->x+48,fs->y+45,50); commitupdate(); while( mouse_buttons == 0 ); abort_msg(""); } Moving a Frame ___________________________________________________________________________ Programmer's Reference Guide - 62 - TEGL Windows Toolkit Chapter 4 - Frames frameselectandmove ___________________________________________________________________________ Function Allows a frame to be moved. This routine is normally called by the teglsupervisor when the right mouse button is held down and the mouse cursor is positioned over a frame. Syntax imagestkptr frameselectandmove(unsigned mxpos, unsigned mypos); Result type Returns a pointer to the frame that the mouse had selected and moved. Remarks The movement of the Frame is under the control of the user until the mouse button is released. To move a frame under program control, use movestackimage. Restrictions This function returns immediately if neither mouse button is held down on entry. See also setmoverestrictions, setframemobility, setmoveframecallproc, movestackimage Example The following example displays a green mouse cursor and calls frameselectandmove whenever the right mouse button is pressed. The routine exits and changes the mouse cursor back to white when the left mouse button is pressed. /* samc04011.c */ #include <graphics.h> #include "teglsys.h" void main() { imagestkptr fs; easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); Programmer's Reference Guide - 63 - TEGL Windows Toolkit Chapter 4 - Frames fs = stackptr; showmouse(); setmousecolor(GREEN); do if (mouse_buttons == 1) fs = frameselectandmove(mouse_xcoord,mouse_ycoord); while( mouse_buttons != 2 ); setmousecolor(WHITE); } ___________________________________________________________________________ setautorotate ___________________________________________________________________________ Function Sets the frame stack auto rotate function. Syntax Macro void setautorotate(char onoff); Remarks Auto rotate is normally set to FALSE. That is, a frame will not automatically rotate to the top of the stack. When set to TRUE any frame that is partially covered will be moved to the top of the stack when teglsupervisor detects a left mouse button click anywhere on the frame. Example /* samc04012.c */ #include <graphics.h> #include "teglsys.h" void main() { imagestkptr fs; Programmer's Reference Guide - 64 - TEGL Windows Toolkit Chapter 4 - Frames easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); pushimage(50,50,150,150); shadowbox(50,50,150,150); setautorotate(TRUE); showmouse(); teglsupervisor(); } ___________________________________________________________________________ setmoverestrictions ___________________________________________________________________________ Function Sets the minimum and maximum coordinates that a frame may be moved. Syntax Macro void setmoverestrictions(imagestkptr frame; unsigned x, unsigned y, unsigned x1, unsigned y1); Remarks Sets the area that a frame is restricted to when frameselectandmove is called. Restrictions The restriction does not apply when a frame is moved using movestackimage. See also frameselectandmove, setframemobility, setmoveframecallproc, movestackimage Example The following sets the frame mobility to the upper half of the screen. Use the right mouse button to move the frame around. /* samc04013.c */ Programmer's Reference Guide - 65 - TEGL Windows Toolkit Chapter 4 - Frames #include <graphics.h> #include "teglsys.h" void main() { easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); setmoverestrictions(stackptr,0,0,getmaxx(),getmaxy() / 2); teglsupervisor(); } ___________________________________________________________________________ setframemobility ___________________________________________________________________________ Function Toggles the ability for a frame to move. Syntax Macro void setframemobility(imagestkptr frame, char movable); Remarks When the mobility of a frame is set to off (FALSE), the frame outline will move when frameselectandmove is called, however, the frame is not moved to the new location when the mouse button is released. The default frame mobility is ON (TRUE). Restrictions The mobility toggle has no effect when a frame is moved using movestackimage. See also frameselectandmove, setmoverestrictions, setmoveframecallproc, movestackimage Programmer's Reference Guide - 66 - TEGL Windows Toolkit Chapter 4 - Frames Example The following example toggles a frames mobility to off. /* samc04014.c */ #include <graphics.h> #include "teglsys.h" void main() { easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); setframemobility(stackptr,FALSE); teglsupervisor(); } ___________________________________________________________________________ setmoveframecallproc ___________________________________________________________________________ Function An event process that is called after an frame has been dragged to a new screen position. Syntax Macro void setmoveframecallproc(imagestkptr frame, callproc p); Remarks Can be used for the trash can effect, originating with the MacIntosh, by which file icons are dragged to the trash can to be deleted from the system. the event may check the mouseclickpos struct (fields ms.x, ms.y, ms.x1, and ms.y1) for the new frame Programmer's Reference Guide - 67 - TEGL Windows Toolkit Chapter 4 - Frames location and whether they overlap the desired frame. Restrictions If you wish for the frame to move to the new location, the event must call movestackimage before returning. See also frameselectandmove, setmoverestrictions, setframemobility, movestackimage Example The following is a very simple Event Handler that simply closes the frame if the frame is moved. /* samc04015.c */ #include "teglsys.h" unsigned poof(imagestkptr ifs, msclickptr ms) { hidemouse(); dropstackimage(ifs); showmouse(); return(0); } void main() { easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); setmoveframecallproc(stackptr,poof); teglsupervisor(); } ___________________________________________________________________________ movestackimage ___________________________________________________________________________ Programmer's Reference Guide - 68 - TEGL Windows Toolkit Chapter 4 - Frames Function Move a frame to a new screen location. Syntax void movestackimage(imagestkptr frame, unsigned x, unsigned y); Remarks Used to move a frame under Program control to a new screen location. x and y are absolute coordinates that specify the upper left corner of the frame at the new location. Restrictions The coordinates are not validated, so care must be taken to ensure that the resulting coordinates of the lower right corner falls within the screen area. See also frameselectandmove, setmoverestrictions, setframemobility, setframecallproc Example The following example moves a smaller frame under another larger frame to demonstrate the integrity of stacked images. /* samc04016.c */ #include "teglsys.h" void main() { imagestkptr fs; unsigned i; easytegl(); pushimage(1,1,20,20); shadowbox(1,1,20,20); fs = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); for(i=0;i<=100;i++) movestackimage(fs,fs->x+2,fs->y+2); while(mouse_buttons == 0); abort_msg(""); } Programmer's Reference Guide - 69 - TEGL Windows Toolkit Chapter 4 - Frames ___________________________________________________________________________ moveframe ___________________________________________________________________________ Function Moves an Xor wire frame from one location to another. Syntax moveframe(int *fx, int *fy, int *fx1, int* fy1, int rx, int ry, int rx1,int ry1, int color); Remarks This only moves a wire frame not the actual frame. The mouse button must be held down on entry or this function returns immediately. rx,ry,rx1,ry1 are the starting coordinates. fx,fy,fx1,fy1 are the coordinates when the mouse button is released. color is the wireframe color. Low Level Frame Functions ___________________________________________________________________________ unlinkfs ___________________________________________________________________________ Function Disconnects a frame from the stack. Syntax void unlinkfs(imagestkptr frame); Remarks UnLinkFS allows you to disconnect a frame from the Image stack to stop any further actions by the frame manager. This procedure is used throughout the window management routines. It is provided as an external routine only for specialized needs. Restrictions This procedure should be used in conjunction with Programmer's Reference Guide - 70 - TEGL Windows Toolkit Chapter 4 - Frames hideimage, showimage, createimagebuffer, dropimagebuffer, and linkfs. If you unlink a frame from the stack without first hiding the frame, the stack manager will not acknowledge the existence of the frame and will overwrite the unlinked frame area. See also linkfs, linkunderfs Example The following example hides the frame before unlinking and dropping the image. /* samc04017.c */ #include "teglsys.h" void main() { imagestkptr fs; easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); showmouse(); while(mouse_buttons == 0); hideimage(fs); unlinkfs(fs); dropimagebuffer(fs); while(mouse_buttons == 0); abort_msg(""); } ___________________________________________________________________________ Programmer's Reference Guide - 71 - TEGL Windows Toolkit Chapter 4 - Frames linkfs ___________________________________________________________________________ Function Reconnects a frame to the stack. Syntax void linkfs(imagestkptr frame1,imagestkptr frame2) Remarks linkfs reconnects frame1 with the frame stack, above frame2. This procedure is used throughout the window management routines. It is provided as an external routine only for specialized needs. Restrictions This procedure should be used in conjunction with hideimage, showimage, createimagebuffer, dropimagebuffer, and unlinkfs. See also unlinkfs, linkunderfs Example The following example performs the same function as rotatestackimage. /* samc04018.c */ #include "teglsys.h" void main() { imagestkptr fs; easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); showmouse(); while(mouse_buttons == 0); hideimage(fs); unlinkfs(fs); Programmer's Reference Guide - 72 - TEGL Windows Toolkit Chapter 4 - Frames linkfs(fs,stackptr); showimage(fs,fs->x,fs->y); while(mouse_buttons == 0); abort_msg(""); } ___________________________________________________________________________ linkunderfs ___________________________________________________________________________ Function Reconnects a frame with the frame stack, below the specified frame. Syntax linkunderfs(imagestkptr frame1,imagestkptr frame2) Remarks linkunderfs reconnects frame1 below frame2. This procedure is used throughout the window management routines. It is provided as an external routine only for specialized needs. Restrictions This procedure should be used in conjunction with hideimage, showimage, createimagebuffer, dropimagebuffer, and unlinkfs. See also unlinkfs, linkfs Example The following example performs the same function as rotateunderstackimage. /* samc04019.c */ #include "teglsys.h" void main() { imagestkptr fs1,fs2; Programmer's Reference Guide - 73 - TEGL Windows Toolkit Chapter 4 - Frames easytegl(); pushimage(1,1,100,100); shadowbox(1,1,100,100); fs1 = stackptr; pushimage(50,50,150,150); shadowbox(50,50,150,150); fs2 = stackptr; showmouse(); while(mouse_buttons == 0); hideimage(fs2); unlinkfs(fs2); linkunderfs(fs2,fs1); showimage(fs2,fs2->x,fs2->y); while(mouse_buttons == 0); abort_msg(""); } ___________________________________________________________________________ createimagebuffer ___________________________________________________________________________ Function Allocates an Image buffer (frame) on the Heap. Syntax void createimagebuffer(imagestkptr *frame, unsigned x, unsigned y, unsigned x1, unsigned y1); Remarks This procedure is used throughout the window management routines. It is provided as an external routine only for specialized needs. Restrictions This procedure should be used in conjunction with hideimage, showimage, createimagebuffer, dropimagebuffer, and unlinkfs. See also dropimagebuffer Example Programmer's Reference Guide - 74 - TEGL Windows Toolkit Chapter 4 - Frames The following example performs the same function as pushimage. /* samc04020.c */ #include "teglsys.h" void main() { imagestkptr fs; easytegl(); createimagebuffer(&fs,1,1,100,100); linkfs(fs,stackptr); getbiti(1,1,100,100,fs->imagesave); shadowbox(1,1,100,100); showmouse(); teglsupervisor(); } ___________________________________________________________________________ dropimagebuffer ___________________________________________________________________________ Function Frees the memory used by the frame on the heap. Syntax void dropimagebuffer(imagestkptr frame); Remarks This procedure is used throughout the window management routines. It is provided as an external routine only for specialized needs. Restrictions This procedure should be used in conjunction with hideimage, showimage, createimagebuffer, dropimagebuffer, and unlinkfs. See also createimagebuffer Programmer's Reference Guide - 75 - TEGL Windows Toolkit Chapter 4 - Frames Example The following example performs the same function as popimage. ___________________________________________________________________________ getfsimage ___________________________________________________________________________ Function Retrieves the screen image within a stacked frame. Syntax void getfsimage(unsigned x, unsigned y, imagestkptr frame); Result type Returns a (non-stacked) frame containing the screen image and other related frame information. Remarks The (non-stacked) frame may be used for replication or it can be merged with other frames. See also putfsimage Example The following example creates a single frame and replicates the frame. ___________________________________________________________________________ putfsimage ___________________________________________________________________________ Programmer's Reference Guide - 76 - TEGL Windows Toolkit Chapter 4 - Frames Function Places the frame saved image anywhere on the screen. Syntax void putfsimage(unsigned x, unsigned y, imagestkptr frame, unsigned rwbits); Remarks rwbits are constants defined in "teglsys.h" which define how the images are placed on the screen. FGNORN replaces screen area with frame image FGAND AND's screen area with frame image. Toggles off screen areas that do no have a frame image. Creates an outline of the frame image. FGOR OR's screen area with frame image. Toggles on empty screen areas that have a frame image. Creates a solid frame image. FGXOR XOR's screen area with frame image. FGNOT Inverts frame image and replaces screen area with image. See also getfsimage Example The following example creates a single frame and replicates the frame. ___________________________________________________________________________ freeimagebuffer ___________________________________________________________________________ Function Frees up the memory allocated for a frame buffer. Syntax void freeimagebuffer(imagestkptr ifs); Remarks Programmer's Reference Guide - 77 - TEGL Windows Toolkit Chapter 4 - Frames This is generally an internal function. Do not use it unless you have a clear understanding of inner workings of the frame stack. ___________________________________________________________________________ getpartialfrontimage ___________________________________________________________________________ Function Gets the partial image of a frame and returns a pointer to a temporary buffer. Syntax imagestkptr getpartialfrontimage(imagestkptr frame, unsigned x, unsigned y, unsigned x1, unsigned y1); Remarks This is a safer way to get the partial image of a frame than using GetBiti. Overlapping frames are partially removed and then restored before returning. ___________________________________________________________________________ getfrontimage ___________________________________________________________________________ Function Get the image of a frame and returns a pointer to a temporary buffer. Syntax Macro imagestkptr getfrontimage(imagestkptr ifs); Remarks This is a safer way to get the image of a frame than using GetBiti. Overlapping frames are partially removed and then restored before returning. ___________________________________________________________________________ pageinfs Programmer's Reference Guide - 78 - TEGL Windows Toolkit Chapter 4 - Frames ___________________________________________________________________________ Function Read an image into memory. Syntax void pageinfs(imagestkptr ifs); Remarks If the image is already in memory then no action is taken. See also pageoutfs. Example This example checks to see if the image is in memory first before attempting to read it in. note that pageinfs check this automatically before reading in an image. if ifs->imagepageout then /* the image is not in memory */ pageinfs(ifs); ___________________________________________________________________________ lockimage ___________________________________________________________________________ Function Locks an frame image into memory. Syntax Macro void lockimage(imagestkptr ifs); Remarks The image is read into memory if required. The lock is maintained until a specific call is made to unlockimage. Lock image can be used where it is desirable to replicate an image on the screen repeatedly. After it is locked then it can be placed on the screen with a call to putbiti. Restrictions This should be used with caution especially if you are Programmer's Reference Guide - 79 - TEGL Windows Toolkit Chapter 4 - Frames locking in a large image. You can fragment the heap and the Virtual Memory Manager may not be able to allocate a large enough memory block for subsequent image swaps. See also unlockimage, useimage, unuseimage Example If the image is less than 64k then it can be copied to Turbo's heap and then the image can be unlocked reducing the chance of a heap error. ___________________________________________________________________________ pageoutfs ___________________________________________________________________________ Function Page out a frame image. Syntax pageoutfs(imagestkptr ifs); Remarks If the image is successfully paged out to ems or disk then teglfreemem is called to free up the memory used. Restrictions If ifs is in use, or locked or already paged out then no action is taken. See also pageinfs. Example pageoutfs(ifs); if (ifs->imagepageout) /* success */ else ; /* failure */ Programmer's Reference Guide - 80 - TEGL Windows Toolkit Chapter 4 - Frames ___________________________________________________________________________ setimagecoordinates ___________________________________________________________________________ Function Sets the frame pointer to a new set of coordinates. Syntax Macro void setimagecoordinates(imagestkptr ifs, unsigned x, unsigned y,unsigned x1,unsigned y1); Remarks A frame's coordinates should not be changed if it is visible. ___________________________________________________________________________ pageoutimagestack ___________________________________________________________________________ Function Requests the virtual memory manager to page out images to make a chunk of memory available. Syntax char pageoutimagestack(unsigned long mem); Remarks mem is the amount of memory required. A large value for mem will result in all image buffers being paged out. This function returns true if the amount of memory requested has been freed. Restrictions Large amounts of memory are required to process image swapping. If you allocate too much and don't free it up as quickly as possible you may get a heap error. Example /* -- force all imagebuffers to disk */ if (pageoutimagestack(512000)) ; /* -- ignore result */ /* -- do whatever needs that much memory */ supersortmemuse(256000); supersort(); /* -- release it before working with windows again */ Programmer's Reference Guide - 81 - TEGL Windows Toolkit Chapter 4 - Frames supersortfreemem(); ___________________________________________________________________________ unlockimage ___________________________________________________________________________ Function Unlocks a frame image. Syntax Macro unlockimage(imagestkptr ifs); Remarks unlock simply sets a flag in the imagestkptr. After unlocking, the Virtual Memory Manager can swap the image to EMS or Disk as required. If the image wasn't locked then no action is taken. Restrictions see restrictions for lockimage. See also lockimage, useimage, unuseimage. Example see example for lockimage. ___________________________________________________________________________ unuseimage ___________________________________________________________________________ Function Flags a frame image as no longer in use. Syntax Macro unuseimage(var ifs : imagestkptr); Remarks This should be called as soon as possible after a useimage to keep as much memory free for the virtual memory manager. Programmer's Reference Guide - 82 - TEGL Windows Toolkit Chapter 4 - Frames See also useimage, lockimage, unlockimage. Example useimage(ifs); /* -- do something with it */ /* -- then let the memory manager swap it out if required */ unuseimage(ifs); ___________________________________________________________________________ useimage ___________________________________________________________________________ Function Makes an image available for use. Syntax Macro useimage(var ifs : imagestkptr); Remarks The frame image is read into memory if not already there and then flagged as being in use. Restrictions if you do prepareforupdate then the in use flag is set to false. See also unuseimage, lockimage, unlockimage. Example useimage(ifs); /* -- do something with it */ /* -- then let the memory manager swap it out if required */ unuseimage(ifs); Programmer's Reference Guide - 83 - TEGL Windows Toolkit Chapter 4 - Frames Mouse Click Areas Mouse click areas are those places on the screen where we sense if the mouse pointer has passed over or has been clicked on. Frames can have mouse click areas on them that are, of course, only available if the frame is visible and the mouse click area is uncovered. The sensitivity of the mouse click area has two levels. The most sensitive is MSSENSE where just having the mouse pointer pass over the area causes an action. The other level is MSCLICK where the mouse pointer must be over the mouse click area and the left mouse button has been pressed. ___________________________________________________________________________ definemouseclickarea ___________________________________________________________________________ Function Attaches an sensitive area of a frame to an event function. Syntax void definemouseclickarea(imagestkptr ifs, unsigned x, unsigned y, unsigned x1, unsigned y1,char active, callproc p, char sense); Remarks ifs is any imagestkptr. the x, y, x1, y1 are coordinates relative to a frame. This means that the upper left corner of a frame is considered 0,0. active is a boolean flag to indicate whether the Mouse Click Area is an active entry TRUE or a place holder FALSE in a list of mouse clicks. A place holder is simply a defined entry with no action recognized. p is the event to call when the Mouse Click Area is activated, either by the mouse pointer passing by the click areas or a mouse click occurring on an click area. nilunitproc may be used to define a no-event handler. This may be used in conjunction with the functions findframe and checkmouseclickpos to check for the respective mouse click activation. Programmer's Reference Guide - 84 - TEGL Windows Toolkit Chapter 4 - Frames nilunitproc may also be used as a temporary parameter. use resetmsclickcallproc to add the proper event handler later. sense is either MSSENSE or MSCLICK. MSSense activates the event handler whenever the mouse cursor passes over the defined mouse click areas. MSCLICK requires the right mouse button to be pressed while the mouse cursor is on the mouse click area. Restrictions The number of mouse click areas is limited only by memory. Overlapping click area take priority over underlying click areas. The coordinates of a Mouse click area must reside within the Frame, otherwise the click areas are not recognized. See also findmouseclickptr, resetmouseclicks, resetmsclicksense, resetmsclickcallproc, resetmsclickactive, checkmouseclickpos Example The following example creates a frame that attaches an 'OK' icon with an Event Handler called DropBoxOption which simply closes the frame and exits. The function CheckforMouseSelect is used to create the illusion of a button being pressed when clicked on. ___________________________________________________________________________ findmouseclickptr ___________________________________________________________________________ Function Searches for a Mouse Click Pointer associated with a Mouse Click Number. Syntax msclickptr findmouseclickptr(imagestkptr ifs, unsigned clicknumber); Result type Programmer's Reference Guide - 85 - TEGL Windows Toolkit Chapter 4 - Frames Returns a mouse click pointer (msclickptr), pointing to a Mouse Click Structure. Remarks Click Numbers are in the order that you define the Mouse Click areas. The first definemouseclickarea is known as Click Number 1, the second is Click Number 2, etc.. In certain instances it is easier to advance through the mouse click areas by Click Numbers. However, most functions, including the calling of Events, pass the Mouse Click Pointer. To translate a Mouse Click Pointer back to a Click Number, use the Mouse Click Pointer fields ie. clicknumber := mouseclickpos->clicknumber where mouseclickpos is of type msclickptr. Restrictions findmouseclickptr returns a NULL if the clicknumber is not found. Compare the resulting msclickptr with NULL before referencing the structure. See also definemouseclickptr, resetmouseclicks, resetmsclicksense, resetmsclickcallproc, resetmsclickactive, checkmouseclickpos Example The following example defines an array of 100 Mouse Click Areas. You may click with the left mouse button on the individual tiles to produce a sound, or on the 'OK' to produce a series of sounds. The function findmouseclickptr is used within the event handler playallnotes to translate a random click number into a note. The function checkformouseselect is used to create the illusion of a button being pressed when clicked on. ___________________________________________________________________________ resetmsclickactive ___________________________________________________________________________ Programmer's Reference Guide - 86 - TEGL Windows Toolkit Chapter 4 - Frames Function Resets the active flag to indicate whether a Mouse Click Area Entry is active or inactive. Syntax void resetmsclickactive(imagestkptr ifs, unsigned mouseclicknumber, char active); Remarks The mouseclicknumber is in the order that you defined the mouse click areas. the first definemouseclickarea is known as mouseclicknumber 1, the second is mouseclicknumber 2, etc.. active is a boolean flag to indicate whether the mouse Click Area is an active entry (TRUE) or a place holder (FALSE) in a list of mouse clicks. A place holder is simple a defined entry with no action recognized. Restrictions if the mouseclicknumber is invalid, the flag is not updated. See also definemouseclickptr, resetmouseclicks, findmouseclickptr, resetmsclicksense, resetmsclickcallproc, checkmouseclickpos Example This example creates an array of 10 buttons which all point to the same event handler switchon. the active flag for a pressed button is turned off to prevent multiple calls to switchon, until another button is pressed. resetmsclickactive is used within switchon to toggle the button active state. ___________________________________________________________________________ resetmsclickcallproc ___________________________________________________________________________ Function Changes the Event Handler for a Mouse click to another Event Handler. Programmer's Reference Guide - 87 - TEGL Windows Toolkit Chapter 4 - Frames Syntax void resetmsclickcallproc(imagestkptr ifs, unsigned mouseclicknumber, callproc p); Remarks mouseclicknumbers are in the order that you define the mouse click areas. the first definemouseclickarea is known as mouseclicknumber 1, the second is mouseclicknumber 2, etc.. p is the event to pass control to when the mouse click area is actived. nilunitproc may be used to define a no-event handler. This may be used in conjunction with the functions findframe and checkmouseclickpos to check for the respective mouse click activation. nilunitproc may also be used to deactivate an event handler. See also definemouseclickptr, resetmouseclicks, findmouseclickptr, resetmsclicksense, resetmsclickactive, checkmouseclickpos Example This example switches between two events that play a different series of sounds. The function checkformouseselect is used to create the illusion of a button being pressed when clicked on. ___________________________________________________________________________ resetmouseclicks ___________________________________________________________________________ Function Removes a chain of mouse click areas from a frame. Syntax void resetmouseclicks(imagestkptr frame, msclickptr clickptr) Remarks the clickptr parameter is the last click pointer from Programmer's Reference Guide - 88 - TEGL Windows Toolkit Chapter 4 - Frames where the remainder of the chain of click areas will be removed. A parameter of NULL removes the Mouse Click Area chain completely. Restrictions the clickptr should be a valid mouseclickptr. Use findmouseclickptr to locate a valid pointer. if clickptr is invalid, the parameter will be treated as NULL. See also definemouseclickptr, findmouseclickptr, resetmsclicksense, resetmsclickcallproc, resetmsclickactive, checkmouseclickpos Example The following example displays a varying number of bars that can be selected. The Event Handler showbarlist plays a sound corresponding to the bar selected and clears the frame and re-displays a new series of bars. ___________________________________________________________________________ resetmsclicksense ___________________________________________________________________________ Function resets the sense parameter associated with a mouse Click Area. Syntax void resetmsclicksense(imagestkptr ifs, char newsense;) Remarks newsense is either MSSENSE or MSCLICK. MSSENSE activates the event handler whenever the mouse cursor passes over the defined mouse click areas. MSCLICK requires the right mouse button to be pressed while the mouse cursor is on the mouse click area. Restrictions resetmsclicksense resets the sense type for the chain of all Mouse Clicks. If you have a mixture of different Programmer's Reference Guide - 89 - TEGL Windows Toolkit Chapter 4 - Frames senses, use a combination of findmouseclickptr and field settings to reset the sense. See also definemouseclickptr, resetmouseclicks, findmouseclickptr, resetmsclickcallproc, resetmsclickactive, checkmouseclickpos Example The following example requires a menu selection to toggle between the menu dropping down automatically or requiring a mouse clickon the menu bar. Keyboard ___________________________________________________________________________ clearkeyboardbuf ___________________________________________________________________________ Function Clears the hardware keyboard buffer. Syntax Macro void clearkeyboardbuf(void); See also clearteglkeyboardbuf. ___________________________________________________________________________ clearteglkeyboardbuf ___________________________________________________________________________ Function Clears the software buffer maintained by the Programmer's Reference Guide - 90 - TEGL Windows Toolkit Chapter 4 - Frames Toolkit. Syntax Macro void clearteglkeyboardbuf(void); Remarks This will discard all pending keystrokes. ___________________________________________________________________________ defineglobalkeyclickarea ___________________________________________________________________________ Function Flexible keycode assignment. Syntax void defineglobalkeyclickarea(imagestkptr ifs, msclickptr ms, unsigned keycode, char repeatkey, callproc,p Remarks ifs is the frame and ms is the mouse click area the key is assigned to, these are passed to p. If ifs and ms are set to nil then the frame and mouse click area that the mouse pointer is over are passed to p. If the mouse pointer is not over a frame then Nil is passed to p. If repeatkey is set TRUE then addition key presses are buffered, otherwise, they are discarded. A special case for this routine is passing 0 as the keycode parameter. In this case any key that is not being trapped for will activate p. The key pressed can be determined by using getch. Restrictions Only the most recently declared key is trapped if a key is trapped more than once. See also definelocalkeyclickarea. ___________________________________________________________________________ definelocalkeyclickarea Programmer's Reference Guide - 91 - TEGL Windows Toolkit Chapter 4 - Frames ___________________________________________________________________________ Function Assign a keycode to a frame and mouse click area. Syntax void definelocalkeyclickarea(imagestkptr ifs, msclickptr ms, unsigned keycode, char repeatkey, callproc p); Remarks ifs is the frame and ms is the mouse click area the key is assigned to, these are passed to p. If repeatkey is set TRUE then additional key presses are buffered otherwise they are discarded. Within a frame definelocalkeyclickarea has prioritry over defineglobalkeyclickarea. See also defineglobalkeyclickarea. ___________________________________________________________________________ dropkeyclick ___________________________________________________________________________ Function Removes a key trap. Syntax void dropkeyclick(imagestkptr ifs, unsigned keycode, callproc p): Remarks If ifs is not NULL then the frame's local key stack is searched first. If the key is not found then the search proceeds to the global key stack. p must match the callproc that the key was originally assigned to. ___________________________________________________________________________ findkeyclickptr ___________________________________________________________________________ Programmer's Reference Guide - 92 - TEGL Windows Toolkit Chapter 4 - Frames Function Locates a key assignment. Syntax keyclickptr findkeyclickptr(imagestkptr ifs, unsigned keycode); Remarks If ifs is not NULL then the frame's local key stack is searched first. If the key is not found then the search proceeds to the global key stack keystackptr. if the keycode is not found then NULL is returned. ___________________________________________________________________________ resetkeyclickcallproc ___________________________________________________________________________ Function Changes the callproc a key is assigned to. Syntax void resetkeyclickcallproc(imagestkptr ifs, unsigned keycode, callproc p); Remarks If ifs is not NULL then the frame's local key stack is searched first. If the key is not found then the search proceeds to the global key stack keystackptr. If keycode is not found then no action is taken. Programmer's Reference Guide - 93 - TEGL Windows Toolkit Chapter 5 - Menus Drop Down, Pop Up Menus ___________________________________________________________________________ The Menu unit is good example of an event library that you can add to the power of TEGL Windows. The generic pull-down or drop-down menus provides a wide range of menu architecture that will meet most application needs. A Menu event uses the standard outtegltextxy and definemouseclickarea functions to list and to create additional mouse click areas on the screen. Even though the menu unit is comprehensive, TEGL Windows Toolkit II is not limited to a standard architecture of menus. The menu unit may be used as an example in creating other types of menu events; such as hanging menus which are not dependent on a bar type selection; or an icon menu, that when clicked on explodes to display a box full of icons that can be selected from. The entries for the menu unit are created and linked at run-time. The entries may be manipulated, copied, or deleted as required within the program. In comparison, some systems offer a external menu compiler which links the menu with the program at compile time. The advantages to an external menu compiler are minimal, and it adds another step in creating a menu system. The advantages to creating dynamic menus at run-time, is the ability to create a menu system that is based on an external text file (ie. the menu text selections may be stored in a text file and read in at run-time to create a menu). Creating a Menu Creating a bar menu is a two step process. The first is to create the entry text list that is associated with a option menu. The second is the creation of the menu bar from which option menus may be selected. You may use the first step by itself to attach an Option Entry list to icon, instead of a bar. Creating a entry text list An entry text list is simply an linked chain of text entries, with a root entry for each text list. +-----------+ +-----------+--+ +-----------+--+ |AnchorOMPtr|----->|OptionMenu |01|------>|OptionMenu |02|----->nil +-----------+ +-----+-----+--+ +-----+-----+--+ * * Programmer's Reference Guide - 94 - TEGL Windows Toolkit Chapter 5 - Menus +-----------+--+ +-----------+--+ |OptionEntry|01| |OptionEntry|01| +-----+-----+--+ +-----+-----+--+ * * +-----------+--+ +-----------+--+ |OptionEntry|02| |OptionEntry|02| +-----+-----+--+ +-----+-----+--+ * * +-----------+--+ nil |OptionEntry|03| +-----+-----+--+ * nil +--------------------------------------------------+ | typedef struct optionmenu { | | optionmptr nextom;------+ | | unsigned numofentries;| | ------->| unsigned maxwidth; +--|-----------> | unsigned padding; | | fontptr fonttype; | | +----- optioneptr firstentry; | | | optioneptr currententry; | | | } optionmenu; | | +------------+ | +-------------------------|------------------------+ * +-----------------------------------------------+--+ | typedef struct optionentry { |01| | +----- optioneptr nextoe; +--| | | char entryline[41]; | | | char entryactive; | | | int entrycolor; | | | callproc entrycallproc; | | | } optionentry; | | +------------+ | +-------------------------|------------------------+ * OM is a short form for an optionmenu structure. This is the header or the root entry for an entry list. The header contains information regarding the number of entries, the maximum width of the entries, the amount of padding on left and right when displayed and the font type that is used. By duplicating the header with a different set of parameters, an Option Entry list may be chained to two or more headers to allow for different fonts. +-----------+ +-----------+ ---->|OptionMenu |----->|OptionMenu |---> +-----+-----+ +-----+-----+ Programmer's Reference Guide - 95 - TEGL Windows Toolkit Chapter 5 - Menus | | |------------------+ | * +-----------+ |OptionEntry| +-----+-----+ * OE is a short form for an optionentry structure. There is no limit to the number of OE records that a list can contain, with the exception that the number of entries cannot be greater than the size of the screen when the OE list is displayed. This is a limitation of the ListOptionMenu functions within the Menu unit and the screen vertical size, rather then a maximum entry limitation. The ListOptionMenu event could be modified to accommodate lists greater then the screen size by displaying a portion of a list and adding another event to display the remainder. The OE record contains the entry (text) line, as well as information on whether the entry line is active or inactive (place holder), its color, and the event that is called when it is selected. ___________________________________________________________________________ createoptionmenu ___________________________________________________________________________ Function Creates an Option Menu header. Syntax optionmptr createoptionmenu(fontptr fonttype); Result type Returns a Option Menu pointer type. Remarks fonttype is one of the fonts in the font library. The option menu header is used to build and reference the option entry list. Use this om pointer when calling the function defineoptions. Restrictions To create multiple om headers with different fonts on a single oe list, use createshadowom to automatically create and link the oe list to a new om header. See also defineoptions, createshadowom Programmer's Reference Guide - 96 - TEGL Windows Toolkit Chapter 5 - Menus Example optionmptr om1, om2; om1 = createoptionmenu(font14); om2 = createoptionmenu(script); ___________________________________________________________________________ defineoptions ___________________________________________________________________________ Function Adds Option Entries to an Option Menu. Syntax void defineoptions(optionmptr om, char *entrystr, char active, callproc p); Remarks The om pointer must be defined by createoptionmenu before option entries may be added. entrystr is the text string to be displayed when the option menu is opened. The entrystr has two types of control character which may be embedded as part of the string. The q - is used to display a dotted separator line between options. To underline a character or a series of characters, add the value of 128 to the ascii value. The underline character is only valid for characters that do not have descenders. Active specifies whether this entry is active (can be selected) or not active. Inactive entries are displayed as jagged characters. p defines the Event that is associated with this menu entry. The p is attached automatically to the option entry when the option menu is displayed. Restrictions Programmer's Reference Guide - 97 - TEGL Windows Toolkit Chapter 5 - Menus There are no limitations on the number of entries that can be defined under a single om header. However, too many entries will list past the bottom of the screen. See also createoptionmenu, createshadowom, underlinechar Example optionmptr om1; om1 = createoptionmenu(font14); defineoptions(om1,"Desktop info...",TRUE,infooption); defineoptions(om1,"--",FALSE,NULL); defineoptions(om1,"Calculator",TRUE,NULL); defineoptions(om1,"Clock",TRUE,NULL); defineoptions(om1,"Snapshot",TRUE,NULL); ___________________________________________________________________________ createshadowom ___________________________________________________________________________ Function Creates a duplicate Option Menu Header with a different Font type. Syntax optionmptr createshadowom(optionmptr om, fontptr fonttype); Result type Returns a new Option Menu pointer type. Remarks om must be an existing optionmenu pointer. fonttype is one of the fonts in the font library. Restrictions The original om pointer must be defined by createoptionmenu before a duplicate option menu header may be created. See also createoptionmenu, resizeoptionmenu Example Programmer's Reference Guide - 98 - TEGL Windows Toolkit Chapter 5 - Menus optionmptr om1,om2; om1 = createoptionmenu(font14); defineoptions(om1,"Desktop info...",TRUE,infooption); defineoptions(om1,"--",FALSE,NULL); defineoptions(om1,"Calculator",TRUE,NULL); defineoptions(om1,"Clock",TRUE,NULL); defineoptions(om1,"Snapshot",TRUE,NULL); om2 = createshadowom(om1,script); ___________________________________________________________________________ resizeoptionmenu ___________________________________________________________________________ Function Allows an Option Menu header to recalculate the size of the option menu window when changing the font type. Syntax void resizeoptionmenu(optionmptr om, fontptr fonttype); Remarks om must be an existing optionmenu pointer. fonttype is one of the fonts in the font library. See also createoptionmenu, createshadowom Example optionmptr om1; om1 = createoptionmenu(font14); defineoptions(om1,"Desktop info...",TRUE,infooption); defineoptions(om1,"--",FALSE,NULL); defineoptions(om1,"Calculator",TRUE,NULL); defineoptions(om1,"Clock",TRUE,NULL); Programmer's Reference Guide - 99 - TEGL Windows Toolkit Chapter 5 - Menus defineoptions(om1,"Snapshot",TRUE,NULL); resizeoptionmenu(om1,script); /* -- Changes the font type Font14 to Script */ ___________________________________________________________________________ togglecheckmark ___________________________________________________________________________ Function Changes the first character of an entry string to 0x30 (check mark) or a 0x32 (space). Syntax void togglecheckmark(unsigned omnum, unsigned oenum, char status); Remarks omnum is the position of the option menu header relative to the anchoromptr. oenum is the position of the option entry relative to the om header. status of 1 will change the first character of the entry to a checkmark, 0 will change the character to a space. See also toggleentrystatus, replaceoptiontext Example optionmptr om1; om1 = createoptionmenu(font14); defineoptions(om1," Show as icons ",TRUE,viewoptiontoggle); defineoptions(om1," Show as text ",TRUE,viewoptiontoggle); defineoptions(om1,"-",FALSE,NULL); defineoptions(om1," Sort by name ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by date ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by size ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by type ",TRUE,viewoptiontoggle); togglecheckmark(1,7,TRUE); Programmer's Reference Guide - 100 - TEGL Windows Toolkit Chapter 5 - Menus /* puts a check mark at the front of Sort by Type */ ___________________________________________________________________________ toggleentrystatus ___________________________________________________________________________ Function Sets an Option entry to active or not active. Syntax void toggleentrystatus(unsigned omnum, unsigned oenum, char status); Remarks omnum is the position of the option menu header relative to the anchoromptr. oenum is the position of the option entry relative to the om header. status of 1 will set the entry as active, 0 will set the entry to nonactive. active specifies whether this entry is active (can be selected) or nonactive. Nonactive entries are displayed as jagged characters. See also togglecheckmark, replaceoptiontext Example optionmptr om1; om1 = createoptionmenu(font14); defineoptions(om1,"Desktop info...",TRUE,infooption); defineoptions(om1,"--",FALSE,NULL); defineoptions(om1,"Calculator",TRUE,NULL); defineoptions(om1,"Clock",TRUE,NULL); defineoptions(om1,"Snapshot",TRUE,NULL); toggleentrystatus(1,5,FALSE); /* toggles snapshot off */ Programmer's Reference Guide - 101 - TEGL Windows Toolkit Chapter 5 - Menus ___________________________________________________________________________ replaceoptiontext ___________________________________________________________________________ Function Replaces Option entry string by another text string. Syntax void replaceoptiontext(unsigned omnum, unsigned oenum, char *entrystr); Remarks omnum is the position of the option menu header relative to the anchoromptr. oenum is the position of the option entry relative to the om header. entrystr is a replacement text string that will be displayed when the Option menu is opened. The entrystr has two types of control character which may be embedded as part of the string. The q - is used to display a dotted separator line between options. To underline a character or a series of characters, add the value of 128 to the ascii value. The underline character only works with characters that do not have descenders. See also togglecheckmark, toggleentrystatus Example optionmptr om1; om1 = createoptionmenu(font14); defineoptions(om1,"Desktop info...",TRUE,infooption); defineoptions(om1,"--",FALSE,NULL); defineoptions(om1,"Calculator",TRUE,NULL); defineoptions(om1,"Clock",TRUE,NULL); defineoptions(om1,"Snapshot",TRUE,NULL); /* -- Replaces "Snapshot" with "Picture" */ replaceoptiontext(1,5,"Picture"); Programmer's Reference Guide - 102 - TEGL Windows Toolkit Chapter 5 - Menus ___________________________________________________________________________ toggleoptionbar ___________________________________________________________________________ Function Inverts mouse click areas. Syntax void toggleoptionbar(imagestkptr ifs, msclickptr, opt, msclickptr lastopt); Remarks opt and lastopt mouse click areas are inverted. It is assumed that lastopt has already been inverted and this call would return it to normal. ___________________________________________________________________________ setoptionmenucolors ___________________________________________________________________________ Function Changes the menu entry colors. Syntax Macro setoptionmenucolors(unsigned activecolor, unsigned inactivecolor); Remarks activecolor is the text color for active entries. inactivecolor is the text color for entries that are currently inactive but have entry positions within the menu. See also setoptionmenubordercolor Example setoptionmenucolors(BLACK,LIGHTGRAY); Programmer's Reference Guide - 103 - TEGL Windows Toolkit Chapter 5 - Menus ___________________________________________________________________________ setoptionmenubordercolor ___________________________________________________________________________ Function Changes the color of the option menu border. Syntax Macro void setoptionmenubordercolors(unsigned color); Remarks color is the color of the border. See also setoptionmenucolors Example setoptionmenubordercolor(WHITE); ___________________________________________________________________________ sethidesubmenu ___________________________________________________________________________ Function Toggles the hiding of sub menus. Syntax void sethidesubmenu(char onoff); Remarks Default is true. When a submenu is pulled down from a bar menu it is normally hidden when a selection is made. If set to 0 then the pulldown is left displayed until the selection that was made returns. Example sethidesubmenu(TRUE); Programmer's Reference Guide - 104 - TEGL Windows Toolkit Chapter 5 - Menus Creating a Bar Menu A bar menu is one of the more popular methods of creating a user interface. As mentioned before, a bar menu is simply another event with the event handler set to baroptionmenu. baroptionmenu is activated whenever the mouse cursor passes by the one of the defined mouse click areas on the bar. when baroptionmenu is activated, optionmenuselection is called in place of the teglsupervisor. There are three activities within a menu system that require a rewrite of the teglsupervisor. optionmenuselection checks if The mouse is clicked outside the menu bar or menu window thus closing any active menus and returning back to the TEGL supervisor. Sensing the mouse cursor movement to another bar entry, thus closing any active menu and opening another menu window. Sensing the mouse cursor moving to another entry within a menu and highlighting the entry. ___________________________________________________________________________ createbarmenu ___________________________________________________________________________ Function Creates a Bar window frame. Syntax void createbarmenu(unsigned x, unsigned y, unsigned ln); Remarks x, y is the position of the bar menu frame. ln is the pixel length of the bar. See also outbaroption Example Programmer's Reference Guide - 105 - TEGL Windows Toolkit Chapter 5 - Menus createbarmenu(0,0,getmaxx); ___________________________________________________________________________ outbaroption ___________________________________________________________________________ Function Attaches an option menu (list) to a displayed text string on the BAR. Syntax void outbaroption(char *entrystr, optionmptr om); Remarks entrystr is the bar text header that is associated with the om list. om is the option menu header returned from createoptionmenu. See also createbarmenu Example optionmptr om1; om1 = createoptionmenu(font14); defineoptions(om1," Show as icons ",TRUE,viewoptiontoggle); defineoptions(om1," Show as text ",TRUE,viewoptiontoggle); defineoptions(om1,"-",FALSE,NULL); defineoptions(om1," Sort by name ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by date ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by size ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by type ",TRUE,viewoptiontoggle); createbarmenu(0,0,getmaxx); outbaroption(" Options ",om1); ___________________________________________________________________________ Programmer's Reference Guide - 106 - TEGL Windows Toolkit Chapter 5 - Menus setbartextcolor ___________________________________________________________________________ Function Changes the default text color on the bar. Syntax Macro void setbartextcolor(unsigned color); Remarks color is the default text color on the bar. See also setbarmenucolor, setbarbordercolor Example setbartextcolor(GREEN); ___________________________________________________________________________ setbarmenucolor ___________________________________________________________________________ Function Changes the bar color. Syntax Macro void setbarmenucolor(unsigned color); Remarks color is the default color for the bar. See also setbarmenucolor, setbarbordercolor Example setbarmenucolor(BLUE); ___________________________________________________________________________ setbarbordercolor ___________________________________________________________________________ Programmer's Reference Guide - 107 - TEGL Windows Toolkit Chapter 5 - Menus Function Changes the bar border color and toggles the border on. Syntax Macro void setbarbordercolor(unsigned color); Remarks color is the default border color for the bar. See also setbartextcolor, setbarborderoff Example setbarbordercolor(GREEN); ___________________________________________________________________________ setbarborderoff ___________________________________________________________________________ Function Toggles the bar border off. Syntax Macro void setbarborderoff(void); Remarks setbarbordercolor resets the border on. See also setbarbordercolor, setbartextcolor Example setbarborderoff(void); ___________________________________________________________________________ setbarshadowtext ___________________________________________________________________________ Programmer's Reference Guide - 108 - TEGL Windows Toolkit Chapter 5 - Menus Function Toggles Bar Shadow Text on/off. Syntax Macro void setbarshadowtext(char onoff) Remarks onoff is either 1 for on and 0 for off. Example setbarshadowtext(TRUE); ___________________________________________________________________________ setbarfillstyle ___________________________________________________________________________ Function Sets the Bar Fill Style. Syntax Macro void setbarfillstyle(unsigned pattern); Remarks Sets the pattern for the bar. The fill patterns are defined by constants in graphics.h. pattern is a numeric type. See also setfillstyle graphics.h. Example setbarfillstyle(BKSLASH_FILL); ___________________________________________________________________________ setbarmenumargin ___________________________________________________________________________ Programmer's Reference Guide - 109 - TEGL Windows Toolkit Chapter 5 - Menus Function Sets the left margin on the barmenu. Syntax Macro void setbarmenumargin(unsigned margin); Remarks margin is the desired left margin where the menu selections start at. This value is in pixels and the default is 16. Can be used if a icon or some symbol should be displayed at the extreme left of the menu. Example setbarmenumargin(32); Icon Option Menus Optionally you can attach a menu to an icon or an area of a frame. The following function adds a drop down menu to any frame area. ___________________________________________________________________________ defineoptionclickarea ___________________________________________________________________________ Function Attaches an option menu (list) to a frame or icon area. Syntax void defineoptionclickarea(imagestkptr ifs, unsigned x, unsigned y, unsigned x1, unsigned y1, optionmptr om, char sense, unsigned char omtype); Remarks ifs is any imagestkptr. x, y, x1, y1 are coordinates relative to a frame. This means that the upper left corner of a frame is considered 0,0. om is the option menu header returned from createoptionmenu. sense is either MSSENSE or MSCLICK. MSSENSE activates the menu event handler whenever the mouse Programmer's Reference Guide - 110 - TEGL Windows Toolkit Chapter 5 - Menus cursor passes over the defined mouse click areas. MSCLICK requires the right mouse button to be pressed while the mouse cursor is on the mouse click area. omtype is the enumerated type of UPPERRIGHT, UPPERLEFT, LOWERRIGHT, and LOWERLEFT, which specifies whether the menu pop-down at the upper right or upper left corner, or pop-up at the lower right or lower left corner. See also definemouseclickarea, resetoptionmenuevents Example optionmptr om1; om1 = createoptionmenu(font14); defineoptions(om1," Show as icons ",TRUE,viewoptiontoggle); defineoptions(om1," Show as text ",TRUE,viewoptiontoggle); defineoptions(om1,"-",FALSE,NULL); defineoptions(om1," Sort by name ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by date ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by size ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by type ",TRUE,viewoptiontoggle); pushimage(530,320,624,340); putpict(530,320,imageCREDITS,BLACK); defineoptionclickarea(stackptr,0,0,93,19,om1,MSCLICK,LOWERRIGHT); ___________________________________________________________________________ resetoptionmenuevents ___________________________________________________________________________ Function Eliminates duplicate menu events where the frame has been closed. Syntax void resetoptionmenuevents(void); Remarks The Menu unit keeps track of menu to frame attachments. In most cases the attachment is permanent, that is, until the program terminates. However in some cases, Programmer's Reference Guide - 111 - TEGL Windows Toolkit Chapter 5 - Menus like the icon editor, the menu to frame attachment changes every time the icon editor explodes or implodes an icon image. Since the Menu unit has no way of knowing whether the attachment still exists, a special function was created to eliminate duplicate or nonexistent event relationships. The only problem with not calling ResetOptionMenuEvents would be an accumulation of menu events for non-existing frames. Eventually the heap area will overflow. See also defineoptionclickarea Example optionmptr om1; om1 = createoptionmenu(font14); defineoptions(om1," Show as icons ",TRUE,viewoptiontoggle); defineoptions(om1," Show as text ",TRUE,viewoptiontoggle); defineoptions(om1,"-",FALSE,NULL); defineoptions(om1," Sort by name ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by date ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by size ",TRUE,viewoptiontoggle); defineoptions(om1," Sort by type ",TRUE,viewoptiontoggle); pushimage(530,320,624,340); putpict(530,320,imageCREDITS,BLACK); defineoptionclickarea(stackptr,0,0,93,19,om1,MSCLICK,LOWERRIGHT); popimage(); pushimage(530,320,624,340); putpict(530,320,imageCREDITS,BLACK); defineoptionclickarea(stackptr,0,0,93,19,om1,MSCLICK,LOWERRIGHT); resetoptionmenuevents(); Programmer's Reference Guide - 112 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers Interrupt Handlers (TEGLIntr) ___________________________________________________________________________ The mouse is perhaps one of the most outlandish devices ever conceived as an interface for computer system (at least in programming it). However, in the world of GUI, the mouse is a mandatory device. Programming for a mouse is a programmer's nightmare, simply because it adds another level of interfacing. Conceptually, keyboard and mice do not mix. As an example, the mouse is dependent on screen location and whether the user had clicked the mouse at a specific location on the screen and whether that location was on an icon. The keyboard, on the other hand, is almost a direct path between pressing a key and executing a subroutine (i.e. if keypress then do something). The programmer is required to write two separate routines for the same function to handle this mix of interfaces. As well, some systems do not have a mouse, so you cannot rely on the mouse pointer being available on all systems. TEGL Windows Toolkit, of course, provides an almost seamless integration of the two devices. On systems without a mouse, TEGL will emulate the mouse by using the cursor keys on the numeric keypad. On systems with a mouse, the cursor keys may be used simultaneously to move the mouse cursor around. A key may also be attached to an icon/event, having the same effect as the mouse clicking on the icon. Interrupts The TEGLIntr unit is comprised of four captured interrupts: The keyboard interrupt (int $09), the mouse subroutine interrupt (function 12), the timer interrupt (int $08) and the control break handler (int $1B). swapteglintroff and swapteglintron should be called just before and after a call to spawn to restore and then to recapture interrupt vectors. ___________________________________________________________________________ swapteglintroff ___________________________________________________________________________ Function Restores all interrupts to the original saved vectors. Syntax void swapteglintroff(void) Remarks Programmer's Reference Guide - 113 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers All interrupts are initially turned on. See also swapteglintron ___________________________________________________________________________ swapteglintron ___________________________________________________________________________ Function Saves and initialize the required TEGL interrupts. Syntax void swapteglintron(void) Restrictions swapteglintron cannot be called more then once in succession, otherwise the system will hang. See also swapteglintron Mouse Emulation The mouse cursor is an internal function of the TEGL mouse unit, rather than using the cursor provided by the mouse driver. This way a mouse cursor is always available even on systems that do not have a mouse. The support for the emulated mouse is identical, in all respects, to the actual mouse driver. In order to provide a seamless integration of the mouse and keyboard, the Mouse function 12 interrupt $33 is used to capture the mouse hardware interrupts, and keyboard interrupt $09 is used to capture key codes. Since both are hardware interrupts, a kbmousebusy flag is used to serialize any conflict if both interrupts occurs at the same time. The emulated mouse cursor is controled by the following primitives. They may be used ONLY if the mouseshow flag is FALSE, otherwise you may find mouse droppings on the screen. ___________________________________________________________________________ mcursoroff ___________________________________________________________________________ Function Switches the Emulated Mouse Cursor off. Programmer's Reference Guide - 114 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers Syntax void mcursoroff(void) Restrictions Use ONLY when mouseshow flag is FALSE. See also mcursoron, msetpos ___________________________________________________________________________ mcursoron ___________________________________________________________________________ Function Switches the Emulated Mouse Cursor on. Syntax void mcursoron(unsigned xpos, unsigned ypos); Remarks xpos, ypos is the relative screen coordinates from the upper left corner of 0,0. Restrictions Use ONLY when mouseshow flag is FALSE. See also mcursoroff, msetpos ___________________________________________________________________________ msetpos ___________________________________________________________________________ Function Sets a new position for the Emulated Mouse Cursor. Syntax void msetpos(unsigned xpos, unsigned ypos); Remarks xpos, ypos is the relative screen coordinates from the upper left corner of 0,0. Restrictions The emulated mouse cursor must be on before setting a new position. Use ONLY when mouseshow flag is FALSE. See also mcursoroff, mcursoron Programmer's Reference Guide - 115 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers Standard Mouse Functions ___________________________________________________________________________ showmouse ___________________________________________________________________________ Function display a mouse cursor at current mouse_xcoord, mouse_ycoord. Syntax void showmouse(void); See also hidemouse, setmouseposition, cursorshape ___________________________________________________________________________ hidemouse ___________________________________________________________________________ Function Hides mouse cursor. Syntax void hidemouse(void) See also showmouse, setmouseposition, cursorshape ___________________________________________________________________________ setmouseposition ___________________________________________________________________________ Function Sets x,y coordinates of mouse cursor. Syntax void setmouseposition(unsigned mousex, unsigned mousey) Remarks mousex, mousey are relative coordinates from the upper left corner of the screen 0,0. See also Programmer's Reference Guide - 116 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers showmouse, hidemouse, cursorshape ___________________________________________________________________________ cursorshape ___________________________________________________________________________ Function Sets the mouse cursor shape. Syntax void cursorshape(masktype shape) Remarks Sets the mouse cursor shape to the bit pattern specified in shape. masktype is predefined as follows: typedef unsigned masktype [2][16]; The mouse shape is based on the underlying byte values contained in the shape array. the shape array is 64 bytes long, with the first 32 bytes corresponding to a 16 by 16 screen mask, and the remaining 32 bytes corresponding to a 16 by 16 cursor mask. The first 32 bytes are ANDed to the screen, followed by ORing the second 32 bytes with the screen pixels to create the final mouse image. For example the pointinghand masktype is defined as a constant as follows: masktype pointinghand /* Screen Mask */ = {{0xE1FF, 0xE1FF, 0xE1FF, 0xE1FF, 0xE1ff, 0xE000, 0xE000, 0xe000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000}, /* Cursor Mask */ {0x1E00, 0x1200, 0x1200, 0x1200, 0x1200, 0x13ff, 0x1249, 0x1249, 0x1249, 0x9001, 0x9001, 0x9001, 0x8001, 0x8001, 0x8001, 0xFFFF}}; The resulting type is: Programmer's Reference Guide - 117 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers Screen Mask 1110000111111111 = 0xE1FF 1110000111111111 = 0xE1FF 1110000111111111 = 0xE1FF 1110000111111111 = 0xE1FF 1110000111111111 = 0xE1FF 1110000000000000 = 0xE100 1110000000000000 = 0xE100 1110000000000000 = 0xE100 0000000000000000 = 0x0000 0000000000000000 = 0x0000 0000000000000000 = 0x0000 0000000000000000 = 0x0000 0000000000000000 = 0x0000 0000000000000000 = 0x0000 0000000000000000 = 0x0000 0000000000000000 = 0x0000 Cursor Mask 0001111000000000 = 0x1E00 0001001000000000 = 0x1200 0001001000000000 = 0x1200 0001001000000000 = 0x1200 0001001000000000 = 0x1200 0001001111111111 = 0x13FF 0001001001001001 = 0x1249 0001001001001001 = 0x1249 0001001001001001 = 0x1249 1001000000000001 = 0x9001 1001000000000001 = 0x9001 1000000000000001 = 0x8001 1000000000000001 = 0x8001 1000000000000001 = 0x8001 1000000000000001 = 0x8001 1111111111111111 = 0xFFFF There are 5 masktype constants defined in the teglntr.c module. They are: pointinghand, hourglass, standard, diagcross, and checkmark. See also showmouse, hidemouse, setmousehotspot ___________________________________________________________________________ Programmer's Reference Guide - 118 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers setmousehotspot ___________________________________________________________________________ Function Sets the cursor hot-spot values relative to the upper-left corner of the mouse cursor image. Syntax void setmousehotspot(unsigned x,unsigned y); Remarks x, y are relative coordinates from the upper left corner of the mouse cursor image 0,0. See also cursorshape ___________________________________________________________________________ setmousecolor ___________________________________________________________________________ Function Sets the mouse cursor color. Syntax void setmousecolor(unsigned color); Remarks Sets the current Mouse Cursor Color to color. Available colors are defined in graphics.h. See also cursorshape ___________________________________________________________________________ mouseposition ___________________________________________________________________________ Function Gets the Mouse Cursor coordinates and button information. Syntax unsigned mouseposition(unsigned *mousex, unsigned *mousey); Result type Returns the mouse button status. Left button - 1, Right button - 2, both buttons - 3. Programmer's Reference Guide - 119 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers Remarks mousex,mousey are relative coordinates from the upper left corner of the screen (0,0). This function is no longer required in version II, since the the information above are provided in the global variables mouse_xcoord, mouse_ycoord and mouse_buttons respectively. See also getbuttonreleaseinfo, getbuttonpressinfo, clearbuttoninfo Example unsigned mp,x,y; mp = mouseposition(x,y); if (mp = 3) /* -- both buttons down */ { } ___________________________________________________________________________ getbuttonreleaseinfo ___________________________________________________________________________ Function Gets the Mouse Cursor button release information. Syntax void getbuttonreleaseinfo(unsigned button, unsigned *buttonstat, unsigned *buttonrelease, unsigned *xpos, unsigned *ypos); Remarks button specifies for which button information is required. buttonstat is the current button status information. buttonrelease is the number of times the button has been released. xpos, ypos specifies the coordinates where the button was last released. Programmer's Reference Guide - 120 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers The information is reset back to zero after the information has been read. See also mouseposition, getbuttonpressinfo, clearbuttoninfo ___________________________________________________________________________ getbuttonpressinfo ___________________________________________________________________________ Function Gets the Mouse Cursor button press information. Syntax void getbuttonpressinfo(unsigned button, unsigned buttonstat, unsigned *buttonrelease, unsigned *xpos, unsigned *ypos); Remarks button specifies for which button information is required. buttonstat is the current button status information. buttonpress is the number of times the button has been pressed. xpos,ypos specifies the coordinates where the button was last pressed. The information is reset back to zero after the information has been read. See also mouseposition, getbuttonreleaseinfo, clearbuttoninfo ___________________________________________________________________________ clearbuttoninfo ___________________________________________________________________________ Function Clears the Mouse button info counters. Programmer's Reference Guide - 121 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers Syntax void clearbuttoninfo(void); See also getbuttonreleaseinfo, getbuttonpressinfo ___________________________________________________________________________ setmouseminmax ___________________________________________________________________________ Function Sets the Mouse Cursor minimum and maximum coordinates. Syntax void setmouseminmax(unsigned minx, unsigned miny, unsigned maxx, unsigned maxy); Remarks MinX, MinY are the minimum relative coordinates that the mouse may travel. MaxX, MaxY are the maximum relative coordinates that the mouse may travel. See also SetMousePosition ___________________________________________________________________________ frozenmouse ___________________________________________________________________________ Function Prevents the mouse from moving when updating the screen. Syntax void frozenmouse(void) Remarks Certain EGA registers cannot be read reliably. Rather then attempting to read and restore the register with each movement of the mouse, it is more economical to simply freeze the mouse, while the screen is being updated. FrozenMouse retains a counter on the number of times the mouse is frozen. In order to unfreeze the mouse, the same number of unfreezemouse calls must be made. Programmer's Reference Guide - 122 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers Restrictions FrozenMouse may be used if the screen update is temporary (i.e. XorBox), or the second EGA page is being updated. Care must be taken that the mouse cursor is not overlapping the updated area, otherwise mouse droppings may result. See also freezemouse, unfreezemouse ___________________________________________________________________________ freezemouse ___________________________________________________________________________ Function Prevents the mouse from moving or being overwritten when updating the screen. Syntax char freezemouse(unsigned x, unsigned y, unsigned x1, unsigned y1); Result type Returns the last MouseShow status. Remarks Certain EGA registers cannot be read reliably. Rather then attempting to read and restore the register with each movement of the mouse, it is more economical to simply freeze the mouse, while the screen is being updated. freezemouse differs from frozenmouse in that a check is made on whether the mouse cursor overlaps the updated area. If the mouse cursor overlaps the update area, the mouse is hidden until unfreezemouse displays the mouse. freezemouse also retains a counter on the number of times the mouse is frozen. In order to unfreeze the mouse, the same number of unfreezemouse calls must be made. Restrictions frozenmouse may be used if the screen update is temporary (i.e. XorBox), or if the second EGA video page is being updated. See also frozenmouse, unfreezemouse Programmer's Reference Guide - 123 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers ___________________________________________________________________________ unfreezemouse ___________________________________________________________________________ Function Releases the mouse from a frozen or freeze status. Syntax void unfreezemouse(char mshow); Remarks mshow is the mouse show status returned from freezemouse, or use the global mouseshow flag if frozenmouse was called. freezemouse and frozenmouse retain a counter on the number of times the mouse is frozen. In order to unfreeze the mouse, the same number of unfreezemouse calls must be made. See also frozenmouse, freezemouse ___________________________________________________________________________ setmousesensitivity ___________________________________________________________________________ Function Sets the mouse-to-cursor movement sensitivity. Syntax void setmousesensitivity(unsigned xsense, unsigned ysense, unsigned threshold); Remarks xsense defines the horizontal movement sensitivity. ysense defines the vertical movement sensitivity. The sensitivity numbers range from 1 through 100, where 50 specifies the default mickey factor of 1. The mouse-to-cursor movement is more sensitive at higher numbers. The threshold parameter sets the ratio at which Programmer's Reference Guide - 124 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers the mouse-to-cursor movement is doubled. This range of this parameter is also 1 through 100. The lower the threshold, the more sensitive the mouse. See also getmousesensitivity ___________________________________________________________________________ getmousesensitivity ___________________________________________________________________________ Function Returns the mouse-to-cursor movement sensitivity scaling factors previously set by setmousesensitivty. Syntax void getmousesensitivity(unsigned *xsense, unsigned *ysense, unsigned *threshold); Remarks xsense defines the horizontal movement sensitivity. ysense defines the vertical movement sensitivity. The sensitivity numbers range from 1 through 100, where 50 specifies the default mickey factor of 1. The mouse-to-cursor movement is more sensitive at higher numbers. The threshold parameter is the ratio at which the mouse-to-cursor movement is doubled. This range of this parameter is also 1 through 100. The lower the threshold, the more sensitive the mouse. See also setmousesensitivity ___________________________________________________________________________ setkeyboardmouse ___________________________________________________________________________ Function Toggles the keyboard mouse on or off. Syntax Programmer's Reference Guide - 125 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers void setkeyboardmouse(char onoff) Remarks The cursor keys leftarrow downarrow uparrow rightarrow, on the keyboard, may be used to emulate the mouse movements. setkeyboardmouse(FALSE) will turn off the emulation, to allow getch to retrieve the keycode. Restrictions setkeyboardmouse will have no effect on keyboard events, (i.e. the cursor keys may be assigned functions by means of addcapturekey), which will have priority over the keyboard mouse. See also setkbsteps, getkbsteps ___________________________________________________________________________ setkbsteps ___________________________________________________________________________ Function Sets the amount of pixel movement with each cursor key press. Syntax void setkbsteps(unsigned xsteps, unsigned ysteps, unsigned sfxsteps, unsigned sfysteps); Remarks xsteps, ysteps are the positive incremental values for moving the mouse cursor to the next position. Initial values are (x=12,y=8). sfxsteps, sfysteps are the positive incremental value for moving the mouse cursor to the next position when using the shiftkey in conjunction with the leftarrow downarrow uparrow rightarrow keys. Initial values are (x=2,y=1). Restrictions setkbsteps will have no effect on keyboard events, (i.e. the cursor keys may be assigned functions by means of addcapturekey), which will have priority over the keyboard mouse. See also setkeyboardmouse, getkbsteps ___________________________________________________________________________ Programmer's Reference Guide - 126 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers getkbsteps ___________________________________________________________________________ Function Returns the pixel movement value set for the keyboard mouse. Syntax void getkbsteps(unsigned *xsteps, unsigned *ysteps, unsigned *sfxsteps, unsigned *sfysteps: word) Remarks xsteps, ysteps are the positive horizontal and vertical step increments. sfxsteps, sfysteps are the positive horizontal and vertical step increments when using the shiftkey in conjunction with the leftarrow downarrow uparrow rightarrow keys. See also setkeyboardmouse, setkbsteps Timer Functions A timer tick has the standard resolution of interrupting any process within the system, 18 times a second. TEGL Windows uses the captured timer interrupt to decrement counters and set a flag when the counter is zero. TEGLSupervisor monitors the status of the flag and calls the attached event when the flag is set. Thus timed events are processed outside the critical timer tick interrupt. Timer events may be used as clocks, background tasks, print spoolers etc. ___________________________________________________________________________ swaptimerout ___________________________________________________________________________ Function Restores the original timer vectors. Syntax void swaptimerout(void) Remarks use swaptimerout if you need to turn the timer Programmer's Reference Guide - 127 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers off. See also swaptimerin ___________________________________________________________________________ swaptimerin ___________________________________________________________________________ Function Captures the original timer vectors and sets the interrupt vectors to point at TEGL's timer function. Syntax void swaptimerin(void) Remarks The timer interrupt is originally swapped in. Restrictions SwapTimerIn cannot be called more then once in succession, otherwise the system will hang. See also SwapTimerIn ___________________________________________________________________________ settimerstart ___________________________________________________________________________ Function Sets the timer value of timepiece counter. Syntax void settimerstart(timerecptr *timepiece, unsigned timeset); Remarks timepiece is of the type timerecptr. if timepiece is set to NULL, a timepiece structure is created and initialized to timeset. timeset is a word value counter. a value of 18 is equivalent of 1 second. See also resettimerflag Programmer's Reference Guide - 128 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers ___________________________________________________________________________ resettimerflag ___________________________________________________________________________ Function Resets the flag that indicates the completion of a cycle. A cycle is when the counter reaches zero and is reset back to its original value. Syntax void resettimerflag(timerecptr timepiece); Remarks timepiece is of the type timerecptr. timepiece is created by settimerstart. See also settimerstart ___________________________________________________________________________ droptimercount ___________________________________________________________________________ Function Deletes a timepiece record from the timer event chain. Syntax void droptimercount(timerecptr timepiece); Remarks timepiece is of the type timerecptr. timepiece is created by settimerstart. See also settimerstart ___________________________________________________________________________ timerswtich ___________________________________________________________________________ Function Toggles the timer handler on or off. Syntax void timerswitch(char onoff) Remarks Programmer's Reference Guide - 129 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers onoff sets the status on whether the timer event chain is scanned and decremented. A value of 0 stops the counters from being decremented. A value of 1 resets the counters back to their original values and causes the counters within the timer event chain to be decremented 18 times a second. timerswitch does not remove the timer interrupt vectors. See also swaptimerout, swaptimerin Keyboard Interrupt Events There are two levels at which the keyboard interrupt may be used. At the higher keyboard event level (monitored by the teglsupervisor), complete events, like swapping rotating windows, may be attached to a key on the keyboard. However, at the lower level setting the keycall parameter in addcapturekey to point at a key handler allows low level functions like positioning the mouse cursor to be performed. A good example of a key handler is the default mouse click handler. The enterkey is used to automatically position the mouse cursor on the first defined mouse click area and simulates the holding down of the mouse right button, until the key is released. The higher Keyboard Event level is set with a call to definelocalkeyclickarea and defineglobalkeyclickarea within teglunit. The keycall parameter in addcapturekey is set to NULL. Instead of calling an external callproc, the keys are stacked in a keyboard buffer that is monitored by the teglsupervisor. This TEGL keyboard buffer is separate from the normal keyboard buffer. The teglkeypressed and teglreadkey functions are provided to check and read captured keys. Note: The keyboard handler uses scan codes rather then translated Ascii codes. Keyboard Scan Codes 0x01 esckey 0x20 key D 0x40 key F6 0x02 key 1key ! 0x21 key F 0x41 key F7 0x03 key 2key @ 0x22 key G 0x42 key F8 0x04 key 3key # 0x23 key H 0x43 key F9 0x05 key 4key $ 0x24 key J 0x44 f10 0x06 key 5key % 0x25 key K 0x45 numlock Programmer's Reference Guide - 130 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers 0x07 key 6key ^ 0x26 key L 0x46 scrlock 0x08 key 7key & 0x27 ; : 0x47 homekey key 7 0x09 key 8key * 0x28 ' " 0x48 uparrow key 8 0x0A key 9key ( 0x29 ` ~ 0x49 pgupkey key 9 0x0B key 0key ) 0x2A shiftkey Left 0x4A key - 0x0C {key -} _ 0x2B {key } 0x4B {leftarrow} {key 4} 0x0D key =key + 0x2C key Z 0x4C key 5 0x0E backspace 0x2D key X 0x4D rightarrow key 6 0x0F forwtabbacktab 0x2E key C 0x4E key + 0x10 key Q 0x2F key V 0x4F endkey key 1 0x11 key W 0x30 key B 0x50 downarrow key 2 0x12 key E 0x31 key N 0x51 pgdnkey key 3 0x13 key R 0x32 key M 0x52 inskey key 0 0x14 key T 0x33 key ,key < 0x53 delkey key . 0x15 key Y 0x34 key .key > 0x54 sysreq 0x16 key U 0x35 key /key ? 0x85 bigfrontF11keyback 0x17 key I 0x36 shiftkey Right 0x86 bigfrontF12keyback 0x18 key O 0x37 prtsckeykey * 0x19 key P 0x38 altkey 0x1A [ { 0x39 {spacebar} 0x1B ] } 0x3A {capslock} 0x1C enterkey 0x3B key F1 0x1D ctrlkey 0x3C key F2 0x1E key A 0x3D key F3 0x1F key S 0x3E key F4 _ 0x3F key F5 ___________________________________________________________________________ addcapturekey ___________________________________________________________________________ Function Adds a keyboard scancode to the keyboard handler for capturing, or for processing immediately when the key is pressed. Syntax void addcapturekey(unsigned keycode, char repeatkey, keybrdcallproc keycall); Remarks keycode is the scan code of the keys on the keyboard. This is different from the ascii code that is usually translated and passed by DOS. Use the scancode value listed in the scancode table. repeatkey is set to 1 if the key is expected to repeat. 0 if the key must be released before Programmer's Reference Guide - 131 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers generating another interrupt. keycall is the key call function when the keyboard handler captures the key. If keycall is set to nilkeycallproc the scancode of the capture key is added to the TEGL keyboard buffer. addcapturekey can stack the same scan code any number of times, however, only the most recent entry in the Scancode chain is used. See also deletecapturekey ___________________________________________________________________________ deletecapturekey ___________________________________________________________________________ Function Removes a keyboard scancode from the keyboard scancode chain. Syntax void deletecapturekey(unsigned keycoded); Remarks keycode is the scan code of the keys on the keyboard. This is different from the ascii code that is usually translated and passed by DOS. If the same scan code is stacked more then once the most recent entry in the Scancode chain is deleted. See also addcapturekey ___________________________________________________________________________ teglreadkey ___________________________________________________________________________ Function Reads a scan code from the TEGL keyboard buffer. Syntax unsigned teglreadkey(void); Result type Returns the first captured scan code in the TEGL Programmer's Reference Guide - 132 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers keyboard buffer. Restrictions Use teglkeypressed to check if any scan codes are in the TEGL keyboard buffer. See also teglkeypressed ___________________________________________________________________________ teglkeypressed ___________________________________________________________________________ Function Returns True if a scan code is captured; False otherwise. Syntax char teglkeypressed(void); Remarks The scan code is added to the TEGL keyboard buffer. See also teglreadkey ___________________________________________________________________________ nilkeycallproc ___________________________________________________________________________ Function Dummy function to use a place holder. Syntax char nillkeycallproc(void); Remarks This function always returns false. See also addcapturekey. Keyboard Miscellaneous ___________________________________________________________________________ setshiftkeys ___________________________________________________________________________ Programmer's Reference Guide - 133 - TEGL Windows Toolkit Chapter 6 - Mouse, Keyboard and Timer Handlers Function Toggles the Shift flags on/off. Syntax void setshiftkeys(unsigned char shiftflag, char onoff); Remarks shiftflag may be one of the types as follows: enum { sk_rightshift = 0x01 }; enum { sk_leftshift = 0x02 }; enum { sk_ctrlshift = 0x04 }; enum { sk_altshift = 0x08 }; enum { sk_scrolllock = 0x10 }; enum { sk_numlock = 0x20 }; enum { sk_capslock = 0x40 }; enum { sk_inslock = 0x80 }; onoff sets the above bits to on 1 or off 0. Show Button Status The tegl.c demonstration program uses the debugunt module to display the mouse button status through a menu selection. ___________________________________________________________________________ showbuttonstatus ___________________________________________________________________________ Function An Event that displays the mouse button status. Syntax unsigned showbuttonstatus(imagestkptr frame, ms mouseclickptr); Remarks Information is displayed on the number of times the mouse buttons have been pressed and released. Shows the last coordinates where the mouse button was pressed and the coordinates where the mouse button was released. Programmer's Reference Guide - 134 - TEGL Windows Toolkit Programmer's Reference Guide - 135 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics Assembler Graphics ___________________________________________________________________________ The fastgrph module is the engine that provides the speed that is seen in the TEGL Windows Toolkit. Most of the graphics tools are written in assembler, with some of the noncritical support routines written in C. Setting Video Modes The following Types and Consts relate to detecting and selecting video modes. The VidID type is passed as a parameter to VideoID to determine the graphics equipment available. struct vidid = unsigned video0type; unsigned display0type; unsigned video1type; unsigned display1type; ; The graphics adaptor card detected is returned in the Video0Type field. Here are a list of the Constants and values and whether they are currently supported by the toolkit. TG_MDA = $01; monochome display, not supported TG_CGA = $02; Color graphics, supported TG_EGA = $03; Enhanced graphics, supported TG_MCGA = $04; Multicolor graphics array, not supported TG_VGA = $05; Video graphics array, not supported TG_HGC = $80; Hercules graphics, supported TG_HGCPlus= $81; Hercules plus, supported TG_InColor= $82; Hercules incolor, supported in 2 color mode ___________________________________________________________________________ cga640x200x2 ___________________________________________________________________________ Function Set the video mode to 640 x 200 in 2 colors. Syntax void cga640x350x2(void); Remarks Programmer's Reference Guide - 136 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics This function uses initgraph to switch to the graphics mode. See also ega640x350x16, herc720x348x2, svga800x600x16, vga640x480x16 ___________________________________________________________________________ ega640x350x16 ___________________________________________________________________________ Function Sets the video mode to 640 x 350 in 16 colors. Syntax void ega640x350x16(void) Remarks This function uses initgraph to switch to the graphics mode. See also cga640x350x2, herc720x348x2, svga800x600x16, vga640x480x16 ___________________________________________________________________________ herc720x348x2 ___________________________________________________________________________ Function Set the video mode to 720 x 350 in 2 colors. Syntax void herc720x348x2(void); Remarks This function uses initgraph to switch to the graphics mode. See also cga640x350x2, ega640x350x16, svga800x600x16, vga640x480x16 ___________________________________________________________________________ setvideochoices Programmer's Reference Guide - 137 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics ___________________________________________________________________________ Function Sets the allowable video modes. Syntax setvideochoices(unsigned vmode, char accept); Remarks By default all video modes are acceptable. Certain programs may not support all video modes. See also videoid, videoautodetect. Example This statement would cause the program to abort if it were run on a machine which only supported CGA graphics. setvideochoices(TG_CGA,FALSE); ___________________________________________________________________________ svga800x600x16 ___________________________________________________________________________ Function Sets the video mode to 800 x 600 in 16 colors. Syntax void svga800x600x16(void); Remarks This function uses initgrph to switch to the graphics mode. Restrictions Requires appropiate hardware support. See also cga640x350x2, ega640x350x16, herc720x348x2, vga640x480x16 ___________________________________________________________________________ vga640x480x16 ___________________________________________________________________________ Programmer's Reference Guide - 138 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics Function Sets the video mode to 640 x 480 in 16 colors. Syntax void vga640x480x16(void); Remarks This function uses initgraph to switch to the graphics mode. Restrictions Requires a VGA card and monitor. See also cga640x350x2, ega640x350x16, herc720x348x2, svga800x600x16 ___________________________________________________________________________ videoautodetect ___________________________________________________________________________ Function Detects the graphics equipment and switches to graphics mode if available. Syntax videoautodetect; Remarks Selects the highest resolution that is available and supported. The global variable InitDriverCode can be examinded to determine the video mode set. See also videoid ___________________________________________________________________________ videoid ___________________________________________________________________________ Function Detects the graphics equipment available. Syntax videoid(strict v *vidid); Remarks Programmer's Reference Guide - 139 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics Graphics equipment is only detected. The current video mode is not changed. Graphic Primitives Turbo C offers a rich set of graphics commands, that work with almost any video display. However, the drawback to the flexibility of Turbo C's BGI Graphics is the speed at which the graphics are displayed. To provide a toolset that could operate quickly, the following assembler graphic routines were written to replace the ones offered by Turbo C. Other then the documented restrictions you may freely mix and match Turbo's graphic routines with TEGL's. The following constants are defined in teglsys.h and may be assigned to RMWBITS to define the type of binary operation between each byte in the line and the corresponding bytes on the screen. unsigned rmwbits; enum { FGNORM = 0x00 }; enum { FGAND = 0x08 }; enum { FGOR = 0x10 }; enum { FGXOR = 0x18 }; enum { FGNOT = 0x80 }; ___________________________________________________________________________ fastline ___________________________________________________________________________ Function Draws a line from (x,y) to (x1,y2). Syntax void fastline(unsigned x,unsigned y,unsigned x1, unsigned y2, unsigned n); Remarks sets the global variable rmwbits to the appropriate mode for drawing the line. x,y specifies the line starting coordinates. Programmer's Reference Guide - 140 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics x1,y1 specifies the line ending coordinates. n specifies the color of the line. Fastline will only draw a continuous line. setlinestyle, setcolor and setwritemode has no effect on fastline. ___________________________________________________________________________ putpixs ___________________________________________________________________________ Function Plots a pixel. Syntax void putpixs(unsigned x, unsigned y, unsigned n); Remarks Plots a point in the color defined by n at (x,y). Set the global variable rmwbits to the appropriate mode for plotting the pixel. Putpixs replaces the PutPixel routine in Graphics.h. See also getpixs ___________________________________________________________________________ getpixs ___________________________________________________________________________ Function Return the pixel value at x,y. Syntax unsigned getpixs(unsigned x,unsigned y) Remarks Gets the pixel color at (x,y). getpixs replaces the getpixel routine in graphics.h. See also putpixs Programmer's Reference Guide - 141 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics ___________________________________________________________________________ getbiti ___________________________________________________________________________ Function Copies the specified screen image into a buffer. Syntax void Getbiti(unsigned x, unsigned y, unsigned x1, unsigned y1, void *buffer) Remarks x,y,x1,y1 defines a rectangular region on the screen. buffer is a memory area that is large enough to hold the resulting image. getbiti replaces the getimage routine in graphics.h. By using cgetmem with bigimagesize, Getbiti will allow saving of images larger than 64k. Restrictons The saved image structure of getbiti and putbiti is different than what getimage and putimage use. See also putbiti, bigimagesize ___________________________________________________________________________ putbiti ___________________________________________________________________________ Function Copies the buffer to the specified screen area. Syntax void putbiti(unsigned x, unsigned y, void *buffer, unsigned rmwbits) Remarks x,y defines the upper left corner of the screen area for placing the saved image. buffer is the image buffer that contains a copy of the screen image saved previously by getbiti. Programmer's Reference Guide - 142 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics rmwbits defines the type of binary operation between the saved image and the corresponding bytes on the screen. putbiti replaces the putimage routine in graphics.h by using cgetmem with bigimagesize, putbiti will allow the saving and restoring of images larger then 64k. Restrictons The saved image structure of getbiti and putbiti is different than what GetImage and PutImage use. See also getbiti, bigimagesize ___________________________________________________________________________ bigimagesize ___________________________________________________________________________ Function Calculates the size of the image buffer. Syntax unsigned long bigimagesize(unsigned x, unsigned y, unsigned x1, unsigned y1); Remarks x,y,x1,y1 defines the rectangular coordinates that will be used for getbiti. bigimagesize replaces the BGI imagesize routine. By using cgetmem with bigimagesize, image buffers may be larger then 64k. See also getbiti, putbiti ___________________________________________________________________________ setapage ___________________________________________________________________________ Function Sets the active page for graphics output. Syntax Programmer's Reference Guide - 143 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics void setapage(unsigned pagenum); Remarks Makes pagenum the active graphics page. All output, including those from the BGI's graphics routines, will be directed to pagenum. Only two pages are supported with the EGA's 640 x 350 x 16 mode. See also setvpage, flipapage, flipvpage, videopage ___________________________________________________________________________ setvpage ___________________________________________________________________________ Function Sets the visual graphics page number. Syntax void setvpage(unsigned pagenum); Remarks Makes pagenum the visual graphics page. All output, including that from the BGI routines, will still be directed to the active pagenum. Only two pages are supported with the EGA's 640 x 350 x 16 mode. See also setapage, flipapage, flipvpage, videopage ___________________________________________________________________________ flipapage ___________________________________________________________________________ Function Flips the active page to the alternate page. Syntax void FlipAPage(void); Remarks Makes the alternate page the active graphics page. All output, including that from the BGI routines, will be directed to the new active page. Programmer's Reference Guide - 144 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics Only two pages are supported with the EGA's 640 x 350 x 16 mode. If the current active page is (1), FlipAPage will set the active page to (2). The reverse is true, if the current active page is (2). flipapage does not have an equivalent in the BGI. See also setapage, setvpage, flipvpage, videopage ___________________________________________________________________________ flipvpage ___________________________________________________________________________ Function Flips the visual page to the alternate page. Syntax void flipvpage(void) Remarks Makes the alternate page the visual graphics page. Only two pages are supported with EGA's 640 x 350 x 16. If the current visual page is (1), flipvpage will set the visual page to (2). The reverse is true, if the current visual page is (2). flipvpage does not have an equivalent in the BGI. See also setapage, setvpage, flipapage, videopage ___________________________________________________________________________ videopage ___________________________________________________________________________ Function Returns the current Visual page. Syntax unsigned VideoPage(void); Remarks Returns the current visual graphics page. Only two pages are supported with the EGA's Programmer's Reference Guide - 145 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics 640 x 350 x 16 mode. videopage does not have an equivalent in the BGI. See also setapage, setvpage, flipapage, flipvpage New Graphic Primitives The TEGL Windows Tookit's ability to display fast graphics is, in a way, just the tip of the iceberg. The following routines provide functions to extract and overlay buffered images before displaying the final results on the screen. Some of these routines may be used to create a virtual image (an image larger then the size of the screen). The only limitation at this time is the need for graphic primitives that will draw to a buffered image. ___________________________________________________________________________ extractpixs ___________________________________________________________________________ Function Return the pixel value at x,y within an image buffer. Syntax unsigned extractpixs(unsigned x, unsigned y, void *buffer) Remarks Gets the pixel color at (x,y) within the saved image buffer. ___________________________________________________________________________ extractimg ___________________________________________________________________________ Function Extract an image area from a buffer. x,y,x1,y1 from buff2 to buff1. Syntax Programmer's Reference Guide - 146 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics void extractimg(unsigned x, unsigned y, unsigned x1, unsigned y1, void *buff1, void *buff2); Remarks Extracts the image defined by x, y, x1, y1 from buff2 and places it in buff1. See also overlayimg, putbiti, getbiti ___________________________________________________________________________ overlayimg ___________________________________________________________________________ Function Overlays buffered image. Syntax void overlayimg(unsigned x, unsigned y, void *buff1, void *buff2); Remarks Overlays an image in buff1 to buff2 at x,y offsets. See also ExtractIMG, PutBiti, GetBiti ___________________________________________________________________________ swapbytes ___________________________________________________________________________ Function Swaps two buffers. Syntax void swapbytes(void *buff1, void *buff2, long bytestoswap); Remarks Swaps the images within buff1 with buff2. Graphic Derivatives The following are some fast common routines to create XOR boxes that can be erased simply by calling the routine again. Programmer's Reference Guide - 147 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics XORing pixels to the screen has the unique feature that when the same pixel is XORed to the same location a second time the pixel is restored to it's original look. The XOR box routines here allow boxes to flit and dance across the screen without (if used correctly) changing any of the underlying display. ___________________________________________________________________________ xorcornerbox ___________________________________________________________________________ Function Creates box corners only. Syntax void xorcornerbox(int x, int y, int x1, int y1, int color); Remarks x,y,x1,y1 are the coordinates of a rectangle. This routine is used in ziptobox and zipfrombox to create the shrinking and expanding corner images. ___________________________________________________________________________ xorbox ___________________________________________________________________________ Function Draws a (xor) rectangle. Syntax void xorbox(int x, int y, int x1, int y1, int color); Remarks (x,y) define the upper left corner of a rectangle, and (x1,y1) define the lower right corner. Coordinates must be within the physical screen. This routine is used in moveframe to move an (xor) box image around. Icon Graphics Programmer's Reference Guide - 148 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics ___________________________________________________________________________ putpict ___________________________________________________________________________ Function Puts an icon to a specified screen area. Syntax void putpict(unsigned x, unsigned y, unsigned char *buf, unsigned n); Remarks x,y defines the upper left corner of the screen area for placing the icon image. buf points to the icon image. n is the default color for any pixel that is black within the icon. See also pictsize, icon editor. ___________________________________________________________________________ pictsize ___________________________________________________________________________ Function Gets the width and height in pixels of an icon image. Syntax void pictsize(unsigned *width, unsigned *height, unsigned char *buffer); Remarks buffer must point to a valid icon image. See also putpict, icon editor. ___________________________________________________________________________ abort_msg ___________________________________________________________________________ Function Closes the graphics system and displays the message string. Programmer's Reference Guide - 149 - TEGL Windows Toolkit Chapter 7 - Assembly Language Graphics Syntax void abort_msg(char *msg); Remarks This routine is defined in fastgrph because of the need for closing the graphics system and returning to text mode before the message can be displayed. Programmer's Reference Guide - 150 - TEGL Windows Toolkit Chapter 8 - Special Effects Special Effects ___________________________________________________________________________ The TEGLGrph unit has a nice collection of graphic effects that may be used to create 3D characters, shadow boxes, long icon buttons, etc.. These routines may be combined with the BGI fonts and graphics for even more effects. We suggest that if you build other graphic effects they should support a standard parameter list. Specifically coordinates should be ordered x, y, x1, y where x, y are the upper left coordinates and x1, y1 are the lower right coordinates of an area on the screen. Screen Backdrop The backdrop is normally the full physical screen filled with a color and pattern to give the effect of a mat. On this mat we place icons and open up windows. It's like the velvet mat a Jeweler uses to show off gem stones. The backdrop does not require a window frame to draw on. ___________________________________________________________________________ clearteglscreen ___________________________________________________________________________ Function Clears the screen to the backdrop pattern. Syntax void clearteglscreen(void); Remarks Fills the complete screen using the bitmask found in teglbackpattern or teglfillstyle with the background color of teglbackcolor. Completes the clearing by placing a border if teglbordershow is TRUE in the color of teglbordercolor. The default is a gray matted area with white borders. Restrictions Must be in Graphics mode. See also setteglbordershow, setteglbackcolor, setteglbordercolor, setteglfillpattern, setteglfillstyle Example Programmer's Reference Guide - 151 - TEGL Windows Toolkit Chapter 8 - Special Effects ega640x350x16(); /* -- sets the graphics mode */ setmouseminmax(0,0,getmaxx(),getmaxy()); clearteglscreen(); ___________________________________________________________________________ setteglbordershow ___________________________________________________________________________ Function Sets the switch on whether a border should be drawn or not drawn after the bar fill. Syntax Macro void setteglbordershow( char bordershow); Remarks Switches the border on=TRUE or off=FALSE when teglclearscreen is called. The default is on TRUE. Restrictions Must be called before calling teglclearscreen. See also teglclearscreen, setteglbackcolor, setteglbordercolor, setteglfillpattern, setteglfillstyle Example setteglbordershow(FALSE); clearteglscreen(); ___________________________________________________________________________ setteglbackcolor ___________________________________________________________________________ Programmer's Reference Guide - 152 - TEGL Windows Toolkit Chapter 8 - Special Effects Function Sets the color of the backdrop. Syntax Macro void setteglbackcolor( unsigned backcolor); Remarks Sets the background color for the backdrop to backcolor. The default is WHITE. Restrictions Must be called before calling teglclearscreen. See also teglclearscreen, setteglbordershow, setteglbordercolor, setteglfillpattern, setteglfillstyle Example setteglbackcolor(GREEN); clearteglscreen(); ___________________________________________________________________________ setteglbordercolor ___________________________________________________________________________ Function Sets the border color of the backdrop. Syntax Macro void setteglbordercolor( unsigned bordercolor); Remarks Sets the border color for the backdrop to bordercolor. The default is WHITE. Restrictions Must be called before calling teglclearscreen. See also teglclearscreen, setteglbordershow, setteglbackcolor, setteglfillpattern, setteglfillstyle Example Programmer's Reference Guide - 153 - TEGL Windows Toolkit Chapter 8 - Special Effects setteglbordercolor(BROWN); clearteglscreen(); ___________________________________________________________________________ setteglfillpattern procedure TEGLGRPH ___________________________________________________________________________ Function Sets the Fill pattern for the backdrop. Syntax Macro void setteglfillpattern( unsigned char backpattern); Remarks Sets the fill pattern for the backdrop to backpattern. unsigned char teglbackpattern[9] = {0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55}; Restrictions Must be called befor calling teglclearscreen to have effect. See also teglclearscreen, setteglbordershow, setteglbackcolor, setteglbordercolor, setteglfillstyle ___________________________________________________________________________ setteglfillstyle ___________________________________________________________________________ Function Sets the Fill style for the backdrop. Syntax Programmer's Reference Guide - 154 - TEGL Windows Toolkit Chapter 8 - Special Effects Macro void setteglfillstyle( unsigned pattern); Remarks Sets the fill style to pattern. Use one of the predefined fill styles from Graphics.h. Setting the fill style cancels the user defined pattern. Restrictions Must be called before calling teglclearscreen. See also teglclearscreen, setteglbordershow, setteglbackcolor, setteglbordercolor, setteglfillpattern Example setteglfillpattern(SOLID_FILL); clearteglscreen(); Creating Shadow Boxes A shadow box is a simple rectangular that has a shadow edge to give a 3-dimensional effect. A shadow box is the quickest method to clear a window after pushimage. ___________________________________________________________________________ shadowbox ___________________________________________________________________________ Function Creates a 3-D type box at the rectangular area defined by x, y, x1, y1. Syntax void shadowbox(unsigned x, unsigned y, unsigned x1, unsigned y1); Remarks x, y, x1, y1 defines the rectangular area for the shadowbox. The default bar SOLID fill color is WHITE with BLACK borders and BLACK shadow. Programmer's Reference Guide - 155 - TEGL Windows Toolkit Chapter 8 - Special Effects See also setshadowcolor, setshadowbordercolor, setshadowfillpattern, setshadowfillstyle Example pushimage(100,100,200,200); shadowbox(100,100,200,200); ___________________________________________________________________________ shadowboxtext ___________________________________________________________________________ Function Outputs a text string within a shadowbox. Syntax void shadowboxtext(unsigned x, unsigned y, unsigned txtlen, char *textstr); See also shadowbox Example shadowboxtext(100,100,200,"Tegl systems corporation"); ___________________________________________________________________________ setshadowcolor ___________________________________________________________________________ Function Sets the bar fill color. Syntax Macro void setshadowcolor(unsigned bcolor); Remarks bcolor defines the shadowbox color. The default bar fill color is WHITE. Programmer's Reference Guide - 156 - TEGL Windows Toolkit Chapter 8 - Special Effects See also shadowbox, setshadowbordercolor, setshadowfillpattern, setshadowfillstyle Example pushimage(100,100,200,200); setshadowcolor(RED); shadowbox(100,100,200,200); ___________________________________________________________________________ setshadowbordercolor ___________________________________________________________________________ Function Sets the shadowbox border color. Syntax Macro void setshadowbordercolor(unsigned bcolor); Remarks bcolor defines the shadowbox border color. The default border color is BLACK. See also shadowbox, setshadowcolor, setshadowfillpattern, setshadowfillstyle Example pushimage(100,100,200,200); setshadowbordercolor(LIGHTGRAY); shadowbox(100,100,200,200); ___________________________________________________________________________ setshadowfillpattern ___________________________________________________________________________ Programmer's Reference Guide - 157 - TEGL Windows Toolkit Chapter 8 - Special Effects Function Sets the bar fill pattern for ShadowBox. Syntax Macro void setshadowfillpattern( unsigned char backpattern); Remarks The default fill pattern is SOLIDFILL which is defined in graphics.h. See also shadowbox, setshadowcolor, setshadowbordercolor, setshadowfillstyle Example unsigned char myshadowpattern[9] = {0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55}; pushimage(100,100,200,200); setshadowfillpattern(myshadowpattern); shadowbox(100,100,200,200); ___________________________________________________________________________ setshadowfillstyle ___________________________________________________________________________ Function Sets the bar fill style for shadowbox. Syntax Macro void setshadowfillstyle( unsigned pattern); Remarks pattern is of one of the predefined type in graphics.h. The default fill style is SOLID_FILL. See also shadowbox, setshadowcolor, setshadowbordercolor, setshadowfillpattern Example pushimage(100,100,200,200); Programmer's Reference Guide - 158 - TEGL Windows Toolkit Chapter 8 - Special Effects setshadowfillstyle(LINE_FILL); shadowbox(100,100,200,200); Creating Shadow Text Shadow text enhances the normal BGI fonts by writing the text string several times with a slight shift of the x,y coordinates on each write. This simple method provides a 3-D quality to any BGI or TEGL font. ___________________________________________________________________________ shadowtext ___________________________________________________________________________ Function Displays a shadowed textstr at (x,y). Syntax void shadowtext(unsigned x,unsigned y, unsigned color, char *textstr); Remarks x,y specifies the coordinates for displaying the textstr. color specifies the color of the textstr. shadowtext is affected by settextstyle, settextjustify and setusercharsize in graphics.h. See also setshadowtexttype, setshadowtextshadow, setshadowtexthighlight, shadowtexthighlightoff Example shadowtext(100,100,LIGHTCYAN,"TEGL systems corporation"); ___________________________________________________________________________ Programmer's Reference Guide - 159 - TEGL Windows Toolkit Chapter 8 - Special Effects setshadowtexttype ___________________________________________________________________________ Function Sets the shadow text font type. Syntax Macro void setshadowtexttype(fontptr texttype); Remarks texttype is a pointer to one of the TEGL fonts. If texttype is set to NULL, shadowtext uses outtextxy in the graphics.h. See also shadowtext, setshadowtextshadow, setshadowtexthighlight, shadowtexthighlightoff Example setshadowtexttype(script); shadowtext(100,100,LIGHTCYAN,"TEGL systems corporation"); ___________________________________________________________________________ setshadowtextshadow ___________________________________________________________________________ Function Sets the shadow color for ShadowText. Syntax Macro void setshadowtextshadow(insigned color); Remarks color is the shadow color when displaying the shadowed text. The default shadow color is BLACK. See also shadowtext, setshadowtexttype, setshadowtexthighlight, shadowtexthighlightoff Example setshadowtextshadow(LIGHTGRAY); Programmer's Reference Guide - 160 - TEGL Windows Toolkit Chapter 8 - Special Effects shadowtext(100,100,LIGHTCYAN,"TEGL systems corporation"); ___________________________________________________________________________ setshadowtexthighlight ___________________________________________________________________________ Function Sets the highlighted color for shadowtext. Syntax Macro void setshadowtexthighlight(insigned color); Remarks color is the highlighted color when displaying the shadowed text. Sormally, shadowtext toggles the high bit of color to achieve the different shadings. See also shadowtext, setshadowtexttype, setshadowtextshadow, shadowtexthighlightoff Example setshadowtexthighlight(BLUE); shadowtext(100,100,LIGHTCYAN,"TEGL systems corporation"); ___________________________________________________________________________ shadowtexthighlightoff ___________________________________________________________________________ Function Resets the highlight color set by setshadowtexthighlight. Syntax void shadowtexthighlightoff(void); Remarks Switches off the highlight color set by setshadowtexthighlight. See also Programmer's Reference Guide - 161 - TEGL Windows Toolkit Chapter 8 - Special Effects shadowtext, setshadowtexttype, setshadowtextshadow, setshadowtexthighlight Example setshadowtexthighlight(BLUE shadowtext(100,100,LIGHTCYAN "TEGL systems corporation"); shadowtexthighlightoff() shadowtext(100,120,LIGHTCYAN,"TEGL systems corporation"); Other text effects ___________________________________________________________________________ extendtextxy ___________________________________________________________________________ Function Makes embossed text. Syntax void extendtextxy(unsigned x, unsigned y, char *sg); Restrictions Does not work with BGI fonts. Example imagestkptr ifs; quickframe(ifs,100,100,300,150); outtegltextxy(105,105,"normal text"); extendtextxy(105,125,"embossed text"); ___________________________________________________________________________ shifttextxy ___________________________________________________________________________ Function Writes text with a leading white edge. Syntax Programmer's Reference Guide - 162 - TEGL Windows Toolkit Chapter 8 - Special Effects void shifttextxy(unsigned x, unsigned y, char *s); Restrictions Does not work with BGI fonts. Remarks x and y are absolute screen coordinates, s is the string to display. Example imagestkptr ifs; setshadowcolor(LIGHTGRAY); quickframe(ifs,100,100,300,150); outtegltextxy(105,105,"normal text"); shifttextxy(105,125,"shifted text"); Buttons ___________________________________________________________________________ definebuttonclick ___________________________________________________________________________ Function Displays an icon, sets mouse click area and attaches it to an Event. Syntax definebuttonclick(imagestkptr ifs, unsigned x, unsigned y, char *button, callproc p); Remarks Ifs is the frame the icon is placed on. Button can be any icon image. p is the event to pass control to when the icon is clicked on. p can be set to collapsetoiconshow or collapsetomsclick if the button is for closing a frame. Example definebuttonclick(ifs,150,200,&imageok,collapsetoiconshow); Programmer's Reference Guide - 163 - TEGL Windows Toolkit Chapter 8 - Special Effects ___________________________________________________________________________ definelongbuttonclick ___________________________________________________________________________ Function Displays a long button with text, sets mouse click area, and attaches it to an event. Syntax void definelongbuttonclick(imagestkptr ifs unsigned x, unsigned y, unsigned ln, char *msg, callproc p); Remarks ifs is the frame the button is placed on. x,y are the coordinates to place the button at. ln is the length of the message in pixels (depends on currently selected font) and msg is the text to place inside the button. p is the event to activate when the button is clicked on. Example definelongbuttonclick(ifs,100,150,35,"Quit",collapsetomsclick); ___________________________________________________________________________ defineuserbuttonclick ___________________________________________________________________________ Function Displays a button with text, sets mouse click area, and attaches it to an event. Syntax void defineuserbuttonclick( imagestkptr ifs, unsigned x, unsigned y, char *msg, callproc p); Remarks ifs is the frame the button is placed on. x,y are the coordinates to place the button at and msg is the text to place inside the button. p is the event to activate when the button is clicked on. Restrictons msg cannot be more than about 4 characters. This is dependant on the currently selected font. Programmer's Reference Guide - 164 - TEGL Windows Toolkit Chapter 8 - Special Effects Example defineuserbuttonclick(ifs,100,150,"Quit",collapsetomsclick); ___________________________________________________________________________ putuserbuttonclick ___________________________________________________________________________ Function Draws a button at the coordinates with a message. Syntax void putuserbuttonclick(imagestkptr ifs, unsigned x, unsigned y, char *msg); Restrictions msg cannot be more than about 4 charcters, depends upon the currently selected font. Remarks This routine just displays a button, no mouse click area is defined. Explosions ___________________________________________________________________________ collapsetoiconshow ___________________________________________________________________________ Function Collapse a frame and restore the icon it came from. Syntax unsigned collapsetoiconshow(imagestkptr ifs, msclickptr ms); Restrictions Should only be attached to a frame created after a call to explodefromiconhide. Remarks After opening a frame from a explodefromiconhide, this Event can be attached to a button within the frame. When Programmer's Reference Guide - 165 - TEGL Windows Toolkit Chapter 8 - Special Effects this button is clicked on, the frame will collapse and zip to the original icon location and restore the icon. See also explodefromiconhide, definebuttonclick. ___________________________________________________________________________ collapsetomsclick ___________________________________________________________________________ Function Collapse a frame and zip back to the original mouse click position. Syntax unsigned collapsetomsclick(imagestkptr ifs, msclickptr ms); Restrictions Should only be attacted to a frame created after a call to explodefrommsclick. Remarks After opening a frame from a explodefrommsclick, this Event can be attached to a button within the frame. When this button is clicked on, the frame will collapse and zip to the original defined mouse click area. See also explodefrommsclick, definebuttonclick. ___________________________________________________________________________ explodefromiconhide ___________________________________________________________________________ Function Hides the icon, zips and opens a new frame. Syntax void explodefromiconhide(imagestkptr : ifs, mouseclickptr ms, unsigned x, unsigned y, unsiigned x1, unsigned y1); Restrictions The icon exploded from must be in a frame of its own for this to look right. Remarks ifs and ms are the parameters passed to an event. x,y,x1,y1 are the coordinates where a new frame is Programmer's Reference Guide - 166 - TEGL Windows Toolkit Chapter 8 - Special Effects to be opened. After a call to this procedure a new frame is created. Save the global variable stackptr if you wish to manipulate the new frame. See also collapsetoiconshow, definebuttonclick. ___________________________________________________________________________ explodefrommsclick ___________________________________________________________________________ Function Zips from a mouse click location to a new frame position. Syntax void explodefrommsclick(imagestkptr ifs, mouseclickpos ms, unsigned x, unsigned y, unsigned x1, unsigned y1); Remarks ifs and ms are the parameters passed to an event. x,y,x1,y1 are the coordinates where a new frame is to be opened. After a call to this procedure a new frame is created. Save the global variable stackptr if you wish to manipulate the new frame. See also collapsetomsclick, defineuserbuttonclick. Moving and Transforming XOR Boxes ___________________________________________________________________________ movebox ___________________________________________________________________________ Function Moves a (XOR) wire frame from x, y to ax, ay. Syntax void movebox(int ax, int ay, int x, int y, int x1, int y1); Remarks x, y, x1, y1 specify the coordinates of the starting (XOR) wire frame. Programmer's Reference Guide - 167 - TEGL Windows Toolkit Chapter 8 - Special Effects ax, ay are the upper left coordinates of the ending position of the (XOR) wire frame. The box movement is divided into 6 steps which is added or subtracted from the originating position until it reaches the destination. The global variable zipduration may be changed to set the delay between each movement step. See also xorbox, xorcornerbox, ziptobox, zipfrombox Example A wire frame box 50(w) x 50(h) is moveed from 100,100 to 500,280. movebox(500,280,100,100,150,150); ___________________________________________________________________________ ziptobox ___________________________________________________________________________ Function Creates a moving and expanding (XOR) wire frame from ax, ay, ax1, ay1 to x, y, x1, y1. Syntax void ziptobox(int ax, int ay, int ax1, int ay1, int x, int y, int x1, int y1); Remarks ax, ay, ax1, ay1 specifies the rectangular coordinates of the starting (XOR) wire frame. x, y, x1, y1 specifies the rectangular coordinates of the ending (XOR) wire frame. The box is moved from (ax,ay) to (x,y) using MoveBox before the box is transformed (expanded). The transformation is divided into 6 steps which is added or subtracted from (ax,ay,ax1,ay1) until the size equals (x,y,x1,y1). The global variable zipduration may be changed to set the delay between each movement step. Programmer's Reference Guide - 168 - TEGL Windows Toolkit Chapter 8 - Special Effects See also xorbox, xorcornerbox, movebox, zipfrombox Example A wire frame box 50(w) x 50(h) at (100,100) will be visually moved and expanded to a box 100(w) x 100(h) at 400,200. ziptobox(100,100,150,150,400,100,500,200); ___________________________________________________________________________ zipfrombox ___________________________________________________________________________ Function Creates a shrinking and moving (XOR) wire frame from x, y, x1, y1 to ax, ay, ax1, ay1. Syntax void zipfrombox(int ax, int ay, int ax1, int ay1, int x, int y, int x1, int y1); Remarks x, y, x1, y1 specifies the rectangular coordinates of the starting (XOR) wire frame. ax, ay, ax1, ay1 specifies the rectangular coordinates of the ending (XOR) wire frame. The box is transformed by dividing the transformation steps into 6 steps which is added or subtracted from (x, y,x1,y1) until the size equals (ax,ay,ax1,ay1). The box is then moved from (x,y) to (ax,ay) using MoveBox. The global variable zipduration may be changed to set the delay between each movement step. See also xorbox, xorcornerbox, movebox, zipfrombox Example A wire frame box 100(w) x 100(h) at (x=400,y=200) will be visually shrunk and moved to a box 50(w) x 50(h) at (x=100,y=100). zipfrombox(100,100,150,150,400,100,500,200); Programmer's Reference Guide - 169 - TEGL Windows Toolkit Chapter 8 - Special Effects Icon Button ___________________________________________________________________________ drawlongbutton ___________________________________________________________________________ Function Creates an icon button of size ln at (x,y). Syntax void drawlongbutton( unsigned x, unsigned y, unsigned ln ); Remarks x,y specifies the coordinates for the icon button. ln specifies the length of the icon button in pixels. Example unsigned x, y; x = 100; y = 100; drawlongbutton(x,y,200); setteglfont(font14); setcolor(WHITE); outtegltextxy(x+15,y+1,"TEGL Systems Corporation"); Programmer's Reference Guide - 170 - TEGL Windows Toolkit Chapter 9 - Writing Events Writing Events ___________________________________________________________________________ All Event-handlers must use the following header definition. unsigned myevents(imagestkptr frame, msclickptr mouseclickpos); This is the declaration of a callproc. It is a far call, you must compile in the large memory model. Mouse Awareness ___________________________________________________________________________ findframe ___________________________________________________________________________ Function Searches through the Frame stack for the first frame that overlaps the coordinates passed as a parameter. Syntax imagestkptr findframe(unsigned mxpos, unsigned mypos); Result type Pointer. Remarks Returns a imagestkptr if the parameters overlap one of the frames, otherwise returns NULL for no match. findframe is used by the teglsupervisor, but is provided as an external function to allow for specialize routines that may be used to replace the teglsupervisor. Restrictions findframe starts the scan from the top of the stack, thereby returning the first frame found that overlaps the parameters. See also checkmouseclickpos Example The following example creates 250 random boxes and monitors the position of the mouse pointer to see if it overlaps one of the boxes. The timer tick routine is Programmer's Reference Guide - 171 - TEGL Windows Toolkit Chapter 9 - Writing Events used to blink the overlapped box, once every second. ___________________________________________________________________________ checkmouseclickpos ___________________________________________________________________________ Function Compares all Mouse click defines within a frame, for a match with the current mouse coordinates. Syntax msclickptr checkmouseclickpos(imagestkptr frame, unsigned mxpos, unsigned mypos); Result type Pointer. Remarks Returns a msclickptr type if mouse coordinates matches one of the mouse click defines, otherwise returns NULL for no match. checkmouseclickpos is normally an internal function, used by the teglsupervisor. The mouse click position information is normally provided as the second parameter of an event, whenever an event is called. However, checkmouseclickpos may be used to rewrite the teglsupervisor or used to determine if the mouse click position has changed. Restrictions findframe should be used first, to check if another frame is overlapping the current frame, before using checkmouseclickpos. See also definemouseclickptr, resetmouseclicks, findmouseclickptr, resetmsclicksense, resetmsclickcallproc, resetmsclickactive Example The following example defines an array of 100 Mouse click areas which uses checkmouseclickpos to establish the mouse location within the frame. Programmer's Reference Guide - 172 - TEGL Windows Toolkit Chapter 9 - Writing Events ___________________________________________________________________________ checkformouseselect ___________________________________________________________________________ Function Checks if one of the mouse click areas within a frame has been selected. Syntax msclickptr checkformouseselect(imagestkptr frame) Result type Returns the Mouse Click Pointer if mouse button was released while the mouse cursor overlaps a button icon. Remarks This function may be used when only the Frame is known and the program is waiting for the user to click on one of a series of unknown icons. checkformouseselect may be used within an event to wait on a multiple button type icon replies from the user. If pressbuttonflag is true, then visualbuttonpress is called to simulate the pressing of a button icon. Restrictions If pressbuttonflag is true, the restrictions for visualbuttonpress should be followed. If the icon does not have a black fringe, set pressbuttonflag to false. See also pressbutton, visualbuttonpress Example The following example creates (8) button type icons, which calls up a window that displays two choices, Cancel or OK. The event waits until one of the choices are made before returning to teglsupervisor. Programmer's Reference Guide - 173 - TEGL Windows Toolkit Chapter 9 - Writing Events Special Effects ___________________________________________________________________________ pressbutton ___________________________________________________________________________ Function Simulates the pressing of a button type icon. The actual routine simply shifts the icon down and to the right by two pixels. Syntax void pressbutton(imagestkptr fs, msclickptr mouseopt); Remarks This function is used mainly by visualbuttonpress to simulate the action of a electronic button switch. pressbutton may be used to create the illusion of a button left in the down position. Restrictions You are required to redraw the button if you need the button in the up position. This routine only works with icons that have a black fringe of two pixels wide on the right and bottom of the icon. The defined mouse click area should not include this shadow area ie. x1 and y1 is less two pixels. See also visualbuttonpress, checkformouseselect Example The following example creates (8) button type icons and toggles the buttons on/off whenever the icon is clicked upon. ___________________________________________________________________________ visualbuttonpress ___________________________________________________________________________ Programmer's Reference Guide - 174 - TEGL Windows Toolkit Chapter 9 - Writing Events Function Performs the pressing and releasing of a button type icon, controlled by the holding down of the left mouse button. Returns when either the user releases the left mouse button or the mouse cursor wanders off the defined mouse click area. Syntax char visualbuttonpress(imagestkptr frame, msclickptr mouseopt); Result type Returns true if mouse button was released while the mouse cursor overlaps with the button icon. Remarks This function may be used whenever the Frame and the Mouse Click Option is known. If the program is waiting for the user to click on one of a series of unknown icons, use checkformouseselect to do an automatic frame and Mouse click Option search. visualbuttonpress is excellent as an entry routine for an event, since the frame and mouse click position are known. Restrictions This routine only works with icons that has a black fringe of two pixels wide on the right and bottom of the icon. The defined mouse click area should not include this shadow area ie. x1 and y1 is less two pixels. See also pressbutton, checkformouseselect Example The following example creates (8) button type icons, allowing the mouse cursor to glide over (while the buttons simulates the on/off motions). A series of beeps are sounded when the mouse button is released with the mouse cursor is on a button. Programmer's Reference Guide - 175 - TEGL Windows Toolkit Chapter 9 - Writing Events Programmer's Reference Guide - 176 - TEGL Windows Toolkit Chapter 10 - Animation Animation ___________________________________________________________________________ The Animation unit provides the tools to animate a series of icons. Combined with the Icon Editor, an event can come to life. Animation in its simplest form is the sequential display of frames. A frame in the sense of the animator is a single still image that is displayed. By linking a series of frames, animation is achieved by displaying each frame in sequence. Animation is as simple as declaring a object, initializing the object, then animating the object. As an example: animateobject bounceicon; resetframe(&bounceicon,1); animateinit(); origin(&bounceicon,604,wy); animate(&bounceicon,8); Animation Overview Animating a series of icons is relatively easy with the functions in the animate module. The hardest part is creating the series of icons and coordinating the movement differences between them. The first step is to declare an variable of animateobject. Here bounceicon is declared as the type animateobject. animateobject bounceicon; The variable bounceicon must be initialized before we can begin adding frame sequences. To initialize bounceicon, use the function init. init(&bounceicon); Programmer's Reference Guide - 177 - TEGL Windows Toolkit Chapter 10 - Animation The next step is to add an icon frame to it. The function addframe adds an icon frame sequence to a animateobject. The parameters are from left to right; the icon constant, defined in TEGLIcon Unit; (-15, 0) the horizontal and vertical travel offset, respectively, on completion of this frame sequence; (14,37) the height and width of the icon; (10) the duration in (milliseconds) before progressing to the next sequence; (0,0) the sound in hertz, and duration; (black) the color replacement for any black pixels in the icon. In this case, black replaces black. addframe(&bounceicon,imageBLANKBUT,-15,0,14,37,10,0,0,black); An object can have a number of different frame sequences. In our example, we need two sequences; a sequence for animating from the right side of the screen to the left side and a sequence for animating from the left to the right. Thus we will label the above frame as Sequence 1. The labels are arbitrary numbers ranging from 0 to 65535. However, you must use this label to switch to the appropriate sequence when the frames are animated. sequence(&bounceicon,1); Use the function resetsequence to reset the counters within the object before creating the second sequence. We then assign the second sequence the arbitrary number of 2. The only difference between this addframe and the last addframe is the horizontal travel offset. Instead of -15, the value is positive, adding to the x coordinate. resetsequence(&bounceicon); addframe(&bounceicon,imageBLANKBUT,15,0,14,37,10,0,0,black); sequence(&bounceicon,2); The function animateinit, replicates the first screen to the second screen. Programmer's Reference Guide - 178 - TEGL Windows Toolkit Chapter 10 - Animation animateinit(&bounceicon); Set the animation origin. In our test program, we will set the icon to the middle of the screen. origin(&bounceicon,getmaxx div 2,getmaxy div 2); To animate the frames, we use the function animate. animate displays the frames until the requested frame count is reached. Since we have only one frame to animate within each sequence, the animator will loop using the same frame until it satisfies the requested frame count. However, since we are working with coordinates, we do not know how many frames it would take to move the icon across the screen. The function destination will perform a test run on the sequence until one of the coordinates is satisfied and passes back a count of the frames needed to reach the destination. Thus, we can use the method Destination with the method animate to finally animate the icon. sequence( &bounceicon, 1); Animate( &bounceicon, Destination( &bounceicon, 36, 0)); Animating from left to right. sequence(&bounceicon, 2); animate(&bounceicon, destination(&bounceicon, 560, 0)); Try experimenting with the example program. You can use the same icon to add a few more frames to each sequence. Vary the travel offsets to see the effect. However, be careful that the resulting travel distance should reach the destination, otherwise the animator will loop forever trying to reach a false destination. As well, the function destination provides only an approximate count of frames to reach the destination. The actual destination coordinate will depend on the travel offset values on each frame added or subtracted from the origin. Programmer's Reference Guide - 179 - TEGL Windows Toolkit Chapter 10 - Animation Animation Functions ___________________________________________________________________________ origin procedure ___________________________________________________________________________ Function Sets the animated object's starting origin. Syntax void origin(animateobject *ao, unsigned ox, unsigned oy); Remarks Sets where the first frame will be displayed. See also getorigin, destination Example apple animateobject; origin(&apple, 100, 100); ___________________________________________________________________________ getorigin ___________________________________________________________________________ Function Gets the animated object's current coordinates. Syntax void getorigin(animateobject *ao, int *lastox, int *lastoy); Remarks Returns the current coordinate from where animate will proceed from. The origins of an animated object will change depending on the travel offset defined in each Programmer's Reference Guide - 180 - TEGL Windows Toolkit Chapter 10 - Animation animation frame. See also origin, destination Example animateobject apple; unsigned lastx, lasty; animate(&apple, 5); getorigin(&apple, &lastx, &lasty); ___________________________________________________________________________ destination ___________________________________________________________________________ Function Returns a count on the number of frames that is needed for animating before the sequence gets the destination coordinates dx,dy. Syntax unsigned destination(animateobject *ao, int dx, int dy); Result type Unsigned. Frame count. Remarks destination will return a count if either x or y coordinates of the origin is less then or greater then the destination dx,dy coordinates. destination is only an approximation of the number of frames required to complete the travel distance. The actual movement is dependent on each frame and its travel offsets. See also origin, getorigin Example animateobject apple; animate(&apple, destination( &apple, 300, 300)); Programmer's Reference Guide - 181 - TEGL Windows Toolkit Chapter 10 - Animation ___________________________________________________________________________ resetframe ___________________________________________________________________________ Function Resets a sequence to begin at any frame number. Syntax void resetframe(animateobject *ao, unsigned startframe); Remarks if startframe is greater then the number of frames in the sequence, the sequence is set at the last frame. startframe of 0 will reset the sequence back to the beginning. See also sequence Example animateobject apple; resetframe(&apple, 0); animate(&apple, 5); ___________________________________________________________________________ sequence ___________________________________________________________________________ Function Sets the sequence pointer. Syntax sequence(animateobject *ao, unsigned seqnum); Remarks seqnum is any number associated with a sequence of frames. If the sequence number does not exist, the Programmer's Reference Guide - 182 - TEGL Windows Toolkit Chapter 10 - Animation method will assume that a new sequence will be created. Creating a new sequence, simply records the seqnum and the start frame. So creating a sequence can occur anytime after adding the first frame. You can continue to add frames after sequence. Use resetsequence to clear and start a new sequence. See also resetsequence, resetframe Example animateobject apple; init(&apple); addframe(&apple,imageAPPLE,mx,my,ht,wd,dl,hz,hzdl,color); addframe(&apple,imageAPPLE,mx,my,ht,wd,dl,hz,hzdl,color); sequence(&apple, 88); ResetSequence(&apple); addframe(&apple,imageAPPLE,mx,my,ht,wd,dl,hz,hzdl,color); addframe(&apple,imageAPPLE,mx,my,ht,wd,dl,hz,hzdl,color); sequence(&apple,99); sequence(&apple, 88); animate(&apple, 5); ___________________________________________________________________________ resetsequence ___________________________________________________________________________ Function Sets the internal data pointers firstframe and currentframe to nil. Syntax void resetsequence(animateobject *ao); Remarks resetsequence will reset the internal data pointers to nil. This will allow a new sequence to begin. Restrictions Use the method sequence to save the data pointers, otherwise all created frames will be lost. See also Programmer's Reference Guide - 183 - TEGL Windows Toolkit Chapter 10 - Animation resetsequence, resetframe Example animateobject apple; init(&apple); addframe(&apple,imageAPPLE,mx,my,ht,wd,dl,hz,hzdl,color); addframe(&apple,imageAPPLE,mx,my,ht,wd,dl,hz,hzdl,color); sequence(&apple,88); resetsequence(&apple); addframe(&apple,imageAPPLE,mx,my,ht,wd,dl,hz,hzdl,color); addframe(&apple,imageAPPLE,mx,my,ht,wd,dl,hz,hzdl,color); sequence(&apple,99); sequence(&apple,88); animate(&apple,5); ___________________________________________________________________________ addframe ___________________________________________________________________________ Function Add a animation frame. Syntax void addframe(animateobject *ao, char *pp, int mx, int my, insigned ht, unsigned wd, unsigned dy, unsigned hz, unsigned hzdy, unsigned co); Remarks addframe is the icon definition pointer. mx,my is the travel offsets that are added to the origin after the icon is displayed. ht,wd is the height and width of the icon. These parameters are used to save the background image before drawing the icon. dy is the delay in milliseconds after displaying the image. hz,hzdy is the frequency of the frame sound, and hzdy is the duration. If the duration of hzdy is Programmer's Reference Guide - 184 - TEGL Windows Toolkit Chapter 10 - Animation longer then the image dy, then dy is used for the frame and the sound is left on after the frame ends. co is the replacement color for the BLACK color pixels defined in the icon. Restrictions Use the function sequence to save the data pointers, otherwise all created frames will be lost. See also resetsequence, resetframe Example animateobject apple; init(&apple); addframe(&apple,imageBLANKBUT,-15,0,14,37,10,0,0,black); animate(&apple, 5); ___________________________________________________________________________ currentframenumber ___________________________________________________________________________ Function Returns the current frame number. Syntax unsigned currentframenumber(animateobject *ao); Result type Unsigned. See also resetframe ___________________________________________________________________________ animateinit ___________________________________________________________________________ Function Replicates the first active screen page to the second in preparation for animating. Programmer's Reference Guide - 185 - TEGL Windows Toolkit Chapter 10 - Animation Syntax void animateinit(void) See also resetframe ___________________________________________________________________________ animate ___________________________________________________________________________ Function Begins the Animation Sequence. Syntax animate(animateobject *ao, unsigned numframe); Remarks numframe is the number of frames to animate. If the number of frames in a sequence is less then the requested numframe, then the sequence loops to the beginning. Restrictions Since animate uses two video pages, the function animateinit must be called to replicate the first page to the second. See also resetframe, destination ___________________________________________________________________________ animatecomplete ___________________________________________________________________________ Function Closes the animation sequence. Syntax void animatecomplete(animateobject *ao); Remarks complete toggles the sound off and resets the frame to the beginning. Example Animation Programmer's Reference Guide - 186 - TEGL Windows Toolkit Chapter 10 - Animation #include <stdio.h> #include <graphics.h> #include "teglsys.h" animateobject bounceicon; void main() { easytegl(); init(&bounceicon); addframe(&bounceicon,imageBLANKBUT,-15,0,14,37,10,0,0,BLACK); sequence(&bounceicon,1); resetsequence(&bounceicon); addframe(&bounceicon,imageBLANKBUT,15,0,14,37,10,0,0,BLACK); sequence(&bounceicon,2); origin(&bounceicon,getmaxx() / 2,getmaxy() / 2); animateinit(); clearkeyboardbuf(); while (!kbhit()) { sequence(&bounceicon,1); animate(&bounceicon,destination(&bounceicon,36,0)); sequence(&bounceicon,2); animate(&bounceicon,destination(&bounceicon,560,0)); } teglsupervisor(); } Programmer's Reference Guide - 187 - TEGL Windows Toolkit Chapter 11 - Writing Text Writing Text ___________________________________________________________________________ the teglwrt module provides the tools to write to the screen using proportional bit-mapped fonts. Unlike BGI fonts, a font may be as small as 5 pixels high and 3 pixels wide. Both BGI vector fonts and TEGL bit-mapped fonts may be used together. Like the BGI outtextxy procedure, teglouttextxy is affected by the settextjustify procedure. To turn off the proportional print, use the procedure setproportional(FALSE). TEGLWrt Variables Bit-mapped Fonts There are 25 bit-mapped fonts available in the teglwrt module They are: font09 font14 countdwn oenglish script ocr fraktur italic georgian apls7 pc9 gaelic litalic pc24 pc3270 m3270 ega09 future broadway script2 lcdfont light14 brdwx19 sansx19 wndwx19 light9 To select a font, just pass it to setteglfont. eg. setteglfont(countdwn). Creating Your Own Bit-mapped Fonts You can create and add your own fonts by modifying the assembler files then assembling the new font to to an object file. Each bit in a byte represents a pixel of the font. The format of a TEGL font is: 1 byte header - indicating the height of the font. Each character is: 1 byte - proportional font width n bytes - defined by the 1 byte header Programmer's Reference Guide - 188 - TEGL Windows Toolkit Chapter 11 - Writing Text TEGLWrt Functions and Procedures fmttegltextxy and outtegltextxy will display characters with underlines. To underline a character in a string, use the macros defined in teglsys.h (A_, B_, C__....._Z_), to append to your string. The following example will underline the T in TEGL. outtegltextxy(100,100,T_"EGL systems corporation"); ___________________________________________________________________________ fmttegltextxy ___________________________________________________________________________ Function Writes formatted output to the graphics screen. Syntax void fmttegltextxy(int x, int y, char *fmt [,argument . . .]); Remarks fmttegltextxy is affected by the justification settings set by settextjustify and color by setcolor. x,y is the coordinates of the graphic screen. fmt is the format string. See printf for a complete discription on format specifications. fonttable is a global variable which is used to set the pointer to an internal font table. See also printf ___________________________________________________________________________ outtegltextxy ___________________________________________________________________________ Function Writes mystr to the graphics screen at x,y. Programmer's Reference Guide - 189 - TEGL Windows Toolkit Chapter 11 - Writing Text Syntax void outtegltextxy(int x, int y, char *mystr); Remarks outtegltextxy is affected by the justification settings set by settextjustify and color by setcolor. x,y is the coordinates of the graphic screen. mystr is the text string for output. fonttable is a global variable which is used to set the pointer to an internal font table. See also teglwrtchar Example settextjustify(CENTER_TEXT,CENTER_TEXT); setcolor(GREEN); setteglfont(script); outtegltextxy(100,100,"TEGL systems corporation"); ___________________________________________________________________________ tegltextwidth ___________________________________________________________________________ Function Returns the proportional width of mystr. Syntax int tegltextwidth(char *mystr); Remarks TEGLTextWidth will scan and total the exact number of pixels mystr will occupy. Restrictions Any unprintable characters will not be included in the final size. See also teglcharwidth, teglcharheight ___________________________________________________________________________ Programmer's Reference Guide - 190 - TEGL Windows Toolkit Chapter 11 - Writing Text teglcharwidth ___________________________________________________________________________ Function Returns the proportional width of a character. Syntax int teglcharwidth(int c); Remarks c is the ordinal value of the character. teglcharwidth will return a value based on the currently selected font. Restrictions Characters outside the 28-126 ascii code will return a invalid size. See also tegltextwidth, teglcharheight ___________________________________________________________________________ teglcharheight ___________________________________________________________________________ Function Returns the height of the proportional font. Syntax int teglcharheight(void); Remarks teglcharheight will return to the first byte in the font table which is the height of the current font. See also tegltextwidth, teglcharwidth ___________________________________________________________________________ teglwrtchar ___________________________________________________________________________ Function Writes a single character to the graphics screen. Syntax void teglwrtchar(int c, int x,int y, int color); Programmer's Reference Guide - 191 - TEGL Windows Toolkit Chapter 11 - Writing Text Remarks x,y specifies the coordinates for writing the character. c is the ascii code of the character. Valid character range is 28-126. color is color of the output character. See also teglouttextxy ___________________________________________________________________________ setproportional ___________________________________________________________________________ Function Switch Proportional font on or off. Syntax Macro void setproportional( char onoff); Remarks Default is proportional font on TRUE. If proportional font is off FALSE, the spacing is 8 bits. ___________________________________________________________________________ setteglfont ___________________________________________________________________________ Function Sets the font to use in subsequent calls to outtegltextxy. Syntax void setteglfont( fontptr p); Remarks This procedure simply sets the fonttable variable to point to p. Showing ALL Fonts FONTTEST.PAS Programmer's Reference Guide - 192 - TEGL Windows Toolkit Chapter 11 - Writing Text The TEGL.C demonstration program uses the fonttest module to display all available fonts, or, individual fonts by selecting from a menu. ___________________________________________________________________________ fontname ___________________________________________________________________________ Function Returns the name of a font. Syntax char *fontname( unsigned fontnum); Remarks fontname is used to build the menu for selective display of fonts. See also showonefont, showfonts ___________________________________________________________________________ showonefont ___________________________________________________________________________ Function An Event that displays a font based on mouseclickpos->clicknumber. Syntax unsigned showonefont(imagestkptr ifs, msclickptr ms); See also FontName, ShowFonts ___________________________________________________________________________ showfonts ___________________________________________________________________________ Function An Event that displays all fonts. Syntax unsigned showfonts(imagestkptr frame, msclickptr ms); Remarks An Event that displays all the available fonts and Programmer's Reference Guide - 193 - TEGL Windows Toolkit Chapter 11 - Writing Text their respective names. See also fontname, showonefont Programmer's Reference Guide - 194 - TEGL Windows Toolkit Chapter 12 - Events Events Library ___________________________________________________________________________ The Event's covered here span over several modules. They may be used immediately in programming an application. The File Selector The file selector selectafile provides a dialogue event, that displays the files of a directory and lets the user select one of the existing files or enter a new file name. The file selector dialogue box allows the user to choose any displayed file either by clicking on the file name and then clicking on the OK button or by clicking on the selection area and typing in the filename. To change directories, position the mouse cursor at a directory filename and click or click at the bar at the top of the file selector window and type in the directory path. selectafile will return the full file name, including the directory prefix, for the file selected. If the Cancel button was clicked or no file was selected, the file name returned will be a NULL. ___________________________________________________________________________ selectafile ___________________________________________________________________________ Function Provides a file selection dialogue that allows a user to choose or create a new filename. Declaration char selectafile(int x, int y, char *path, char *fileselected); Result type Toolean. True if a file was selected. False if no file was selected or the mouse clicked on the cancel button. Remarks x,y is the coordinates where the file selection dialogue will be displayed. path is the original directory path specification. Use a global string variable to retain the last directory path. fileselected will contain the selected path and Programmer's Reference Guide - 195 - TEGL Windows Toolkit Chapter 12 - Events filename, if the function returns True. String Editing Dialog The EditString procedure provides a facility for getting text input from the user. The file selector uses this routine to get a new filename. ___________________________________________________________________________ editstring ___________________________________________________________________________ Function Provides string input facility. Declaration void editstring(imagestkptr fs, int x, int y, int maxlen, char *textstr); Remarks fs is of the type imagestkptr, created by pushimage. x,y is the relative coordinates from the upper left of fs where a blinking vertical bar and text input will be displayed. maxlen is the number of maximum number of input characters. textstr is the user input string. Restrictions String editing should be on the topmost window. Example char mystring[12]; pushimage(100,100,150,150); setteglfont(font14); editstring(stackptr,5,5,12,&mystring); Mouse Sensitivity Dialogue Window The mouse sensitivity dialogue box allows the user to change the horizontal, Programmer's Reference Guide - 196 - TEGL Windows Toolkit Chapter 12 - Events vertical and threshold settings of the mouse. The dialogue box consists of radio type buttons that can adjust the numeric counters. ___________________________________________________________________________ setmousesense ___________________________________________________________________________ Function Provides a mouse sensitivity dialogue window that allows the user to change the sensitivity setting of the mouse. Declaration void setmousesense(int x, int y); Remarks x,y is the coordinates where the SetMouseSense dialogue will be displayed. Restrictions The dialogue does not check if the mouse is present. Example unsigned askmousesense(imagestkptr frame, msclickptr mouseclickpos); { setmousesense(160,75); return(1); } Bells & Whistles, Sound Unit the asksoundsense dialogue window allows the user to change the duration of the beeps and whistle settings of the sound unit. The dialogue box consists of radio type buttons that can adjust the numeric counters. ___________________________________________________________________________ asksoundsense ___________________________________________________________________________ Function A sound duration dialogue event Programmer's Reference Guide - 197 - TEGL Windows Toolkit Chapter 12 - Events Syntax unsigned asksoundsense( imagestkptr frame, msclickptr ms); Remarks An event that displays a dialogue box that permits the user to set the sound duration for beeps and whistles. ___________________________________________________________________________ beep ___________________________________________________________________________ Function Toggles the sound on for a specific tone and duration for n times. Declaration void beep(unsigned tone, unsigned n, unsigned duration); Remarks tone specifies the frequency of the emitted sound in hertz. n specifies the number of times the sound it toggle on and off. duration specifies the length in milliseconds of the sound. See also slidebeep, soundswitch Example beep(1000,3,100); ___________________________________________________________________________ slidebeep ___________________________________________________________________________ Function Programmer's Reference Guide - 198 - TEGL Windows Toolkit Chapter 12 - Events Performs a sliding type of sound. Whistle type. Declaration void slidebeep(unsigned tone1, unsigned tone2, unsigned n); Remarks tone1 specifies the initial frequency of the emitted sound in hertz. tone2 specifies the second frequency from which tone1 steps towards. n specifies the number of times the slide beep occurs. See also beep, soundswitch Example slidebeep(1000,2000,2); ___________________________________________________________________________ soundswitch ___________________________________________________________________________ Function Switches the sound function on/off. Declaration void soundswitch(char onoff); Remarks onoff switches the sound on-1 or off-0. See also beep, slidebeep Programmer's Reference Guide - 199 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager Virtual Memory Manager ___________________________________________________________________________ Graphical images, by their nature, require a tremendous amount of memory to store and manipulate. Combine this with the DOS limitation of 640k, writing applications using a graphical environment can be limiting. Virtual Memory is a concept by which less expensive mass storage devices (ie. hard disk) may be used as though it were an extension of memory. Then memory is only limited by the size of the hard disk. The TEGL virtual memory manager may be used within your application program independent of its use within the TEGL window manager. In this chapter, we provide technical information for advanced programmers. We'll cover topics such as the Virtual Memory Manager, Turbo C's heap manager, Expanded Memory Manager, calling conventions, and more. malloc, calloc, free, and other Turbo C memory allocation functions are replaced in TEGL by cgetmem and cfreemem. cgetmem and cfreemem are available in TEGL for memory allocation within your Turbo C functions. When cgetmem is used, the virtual memory manager will automatically swap any images, that is not currently active, to EMS or your hard disk, thus freeing enough memory to fulfill your request. Heap Management With Window Management routines, the memory requirement is unknown. If we were to attempt to ensure that memory is available for every window that is created within the program, we would have an unwieldy and unjustifiably large program. In actual fact, any modest application would require much more memory than is available. Rather then attempting to reserve a fixed amount of memory space, which places a limitation on the program, the heap provides the facility of allocating memory dynamically. The heap permits us to allocate memory only when it is required and to release the memory when the task is completed. The Heap Manager When the virtual memory manager is initialized, a block of memory is allocated from Turbo C's far heap. The default when initializing from teglinit(), is all the remaining memory that is left when a program is executed. If you need to reserve a part of the far heap for C library functions (eg. file streams), that uses malloc, calloc etc. you can use the Macro setheapmemmaxsize(maxsize) to reduce the virtually memory manager from grabbing all of the far heap. Programmer's Reference Guide - 200 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager The virtual memory manager is identical with Turbo C's heap manager, in its operation of allocating from the reserved memory starting starting with the lowest part of the heap growing upwards. The bottom of the heap is stored in the variable heaporg. Each time a block of memory is allocated on the heap (via cgetmem or fgetmem), the heap manage moves heapptr upward by the size of the requested block. The top of the heap, or the maximum size of the heap is controlled by the variable freeptr. It does not point directly at the maximum top, rather it points at the start of the free pointer chain. The free pointer chain grows downward as memory blocks are freed. Adjacent memory blocks are always combined to form larger blocks. The Virtual Heap Manager allows us to allocate memory blocks that are greater than 64k. A full EGA screen image (640x350 -16 colors) is approximately 109k. The cgetmem differs from fgetmem in that the virtual heap manager will search through the free space chain and reuses the first available memory block that can accommodate the request. When a memory request is made to fgetmem, the manager will attempt to allocate memory between HeapPtr and FreePtr first, before attempting to find space on the free space list. fgetmem is normally not used as part of your TEGL application. The TEGL Heap Error Function The hugeheaperror variable allows you to install a heap error function, which gets called whenever the TEGL heap manager cannot complete an allocation request. hugeheaperror is a pointer that points to a function with the following header: int myheaperror(unsigned long heapsize) The TEGL heap error function is installed by assigning its address to the hugeheaperror variable: hugeheaperror = myheaperror; The TEGL heap error function gets called whenever a call to cgetmem cannot complete the request. The size parameter contains the size of Programmer's Reference Guide - 201 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager the block that could not be allocated, and the TEGL heap error function should attempt to free a block of at least that size. Depending on its success, the TEGL heap error function may return a 1 or 2. A return of 2 indicates success and causes a retry (which could also cause another call to the TEGL heap error function). A return of any other value will cause cgetmem to return a NULL pointer. The standard TEGL heap error function always returns a 1, causing cgetmem to return a NULL pointer. TEGLunit sets the heap error function to point to the virtual memory manager. Don't use the heap error function if you are using TEGLUnit, the virtual memory handler depends on this function to know when its time to start paging out window buffers. The TEGL Heap Manager Functions ___________________________________________________________________________ cgetmem ___________________________________________________________________________ Function Returns a pointer to a memory block of the specified size. Syntax void far * cgetmem(unsigned long heapsize) Remarks Returns a (void) pointer. Size is a unsigned long specifying the size, in bytes, of the memory block to allocate. If there isn't enough free space on the heap to allocate the memory block, the return pointer is NULL. A user defined run-time error procedure can be used to intercept any heap errors (see hugeheaperror). Restrictions There are actually no restrictions on the size of the largest block that can be allocated, however, DOS limits you to the remaining memory after the program is loaded. See also cfreemem Example Allocates and frees a 128k buffer. Programmer's Reference Guide - 202 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager #include "teglsys.h" void main() { char far * buffer; buffer = cgetmem(131072); cfreemem(buffer,131072); } ___________________________________________________________________________ cfreemem ___________________________________________________________________________ Function Frees a memory block and returns the memory back to the heap manager. Syntax void cfreemem(void far * freeorgptr, unsigned long heapsize) Remarks freeorgptr is a pointer variable of any pointer type that was previously assigned by the cgetmem or fgetmem function. Size is an unsigned long specifying the size of the memory block, in bytes, to be freed; it must be exactly the same number of bytes previously allocated to that memory block by cgetmem or fgetmem. cfreemem returns the memory region to the TEGL heap. Restrictions Do not use cfreemem to free up memory allocated by Turbo's C heap manager. See also cgetmem Expanded Memory Manager (EMM) The Expanded Memory Manager is a device driver that controls and manages expanded memory and application programs that use expanded memory. Expanded memory is memory beyond DOS's 640K-byte limit. The Expanded Memory specification (EMS) supports up to 32M bytes of expanded memory. Because the 8086, 8088, and 80286 (in real mode) microprocessors can Programmer's Reference Guide - 203 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager physically address only 1M byte of memory, they access expanded memory through a window in their physical address range. This is similar to a book, where pages within the book can retain data. However, just like a book, if you wish to retrieve the data, you must supply the page number. As well, when you first create the book (returning a handle) the initial number of pages must be specified. If you require more pages after the initial allocation, a new book must be created (Version 3.2 EMS did not provide a function that allows you to expand the initial allocation with the same handle). There are approximately 30 EMS functions calls available with EMS Version 4.0; as documented in the specification produced jointly by Lotus Development Corporation, Intel Corporation, and Microsoft Corporation. A copy of this documentation (Part number 300275-005) October, 1987, can be obtained from Intel Corporation, 3065 Bowers Avenue, Santa Clara, CA 95051. However, EMM Version 3.2 is still widely used as the driver on most systems, and therefore we are limited in terms of compatibility, to the number of functions that may be used. Expanded Memory Functions ___________________________________________________________________________ emminstalled ___________________________________________________________________________ Function Returns an installed status on the Expanded Memory Manager. Syntax char emminstalled(void) Result type Returns a char status of 1, if an EMM driver is installed on the system, 0 if not installed. Remarks This function uses the address that is found in the Int 67H vector to inspect the device header of the presumed EMM. If the EMM is present, the name field at offset 0AH of the device header will contain the string EMMXXXX0. Programmer's Reference Guide - 204 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager ___________________________________________________________________________ emspagesavailable ___________________________________________________________________________ Function Obtains the total number of expanded memory pages present in the systems, and the number of those pages that are not already allocated. Syntax unsigned emspagesavailable(unsigned *total_ems_pages, unsigned * pages_available) Result type Returns a return code of 0 if EMM software is successful. A return code other then 0 indicates a possible error in the EMM software or a memory hardware error. Remarks This function may be used to determine the number of pages available before allocating EMS pages. ___________________________________________________________________________ allocateexpandedmemorypages ___________________________________________________________________________ Function Allocates the requested number of pages (16k per page) and returns a handle that is used to reference the allocated pages. Syntax unsigned allocateexpandedmemorypages(unsigned pages_needed, unsigned * handle) Result type Returns a return code of 0 if EMM software is successful. A return code of $88 indicates that the requested sh PagesNeeded is greater then the number of pages that is currently available in the system. See also mapexpandedmemorypages, getpageframebaseaddress, deallocateexpandedmemorypages Programmer's Reference Guide - 205 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager ___________________________________________________________________________ mapexpandedmemorypages ___________________________________________________________________________ Function Maps one of the logical pages of expanded memory assigned to a handle onto one of the four physical pages within the EMM's page frame. Syntax unsigned mapexpandedmemorypages(unsigned handle, unsigned logical_page,unsigned physical_page) Result type Returns a return code of 0 if EMM software is successful. A return code of $8A indicates that the logical page requested to be mapped is outside the range of pages that is currently assigned to the handle. Remarks A logical page is one page from the range of pages that were allocated through the sh allocateexpandedmemorypages function. The logical-page number must be in the range {0_._._._n_-_1}}, where {it n} is the number of logical pages previously allocated. A physical page is one of four 16k byte pages, in the range of 0-3, that may viewed as the window to the expanded memory. Use sh getpageframebaseaddress to obtain the segment address to the physical window. See also allocateexpandedmemorypages, getpageframebaseaddress, deallocateexpandedmemorypages ___________________________________________________________________________ getpageframebaseaddress ___________________________________________________________________________ Function Returns the segment address of the page frame used by the Expanded Memory Manager. Syntax unsigned getpageframebaseaddress(unsigned *page_frame_address) Result type Programmer's Reference Guide - 206 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager Returns a return code of 0 if EMM software is successful. A return code other then 0 indicates a possible error in the EMM software or a memory hardware error. Remarks This is only the segment address of the physical page frame. Use offsets of $0000 for physical page 0, offset of $4000 for page 1, offset of $8000 for page 2 and offset of $C000 for page 3. See also allocateexpandedmemorypages, mapexpandedmemorypages, deallocateexpandedmemorypages ___________________________________________________________________________ deallocateexpandedmemorypages ___________________________________________________________________________ Function Deallocates (releases) the pages of expanded memory currently assigned to a handle. Syntax unsigned deallocateexpandedmemorypages(unsigned handle) Result type Returns a return code of 0 if EMM software is successful. Remarks This function notifies the Expanded Memory Manager that the application will not be making further use of the allocated expanded memory pages. This function would typically be called by a program just before performing an exit. See also allocateexpandedmemorypages, mapexpandedmemorypages, getpageframebaseaddress. ___________________________________________________________________________ getversionnumber ___________________________________________________________________________ Programmer's Reference Guide - 207 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager Function Returns the EMM Version Number in a string format. A handle. Syntax unsigned getversionnumber(char * version_string) Result type Returns a return code of 0 if EMM software is successful. A return code other then 0 indicates a possible error in the EMM software or a memory hardware error. Remarks This function returns a EMM Version Number that may be used to check if the installed EMM will support the requested functions. However since Version 4.00 of the expanded memory specification is downward compatible with Version 3.2, this function is only useful as information. ___________________________________________________________________________ gethandlecountused ___________________________________________________________________________ Function Returns the number of total handles used by all applications. a handle. Syntax unsigned gethandlecountused(unsigned *numberofhandles) Result type Returns a return code of 0 if EMM software is successful. A return code other then 0 indicates a possible error in the EMM software or a memory hardware error. Remarks The number of available handles depends on the parameters used to start up the EMM driver, as well as the number of handles in use by other resident or multitasking software. The upper limit in Version 4.00 is 255 handles with a lower limit of 32. If the returned number of handles is zero, the EMM is idle and none of the expanded memory is in use. ___________________________________________________________________________ Programmer's Reference Guide - 208 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager getpagesownedbyhandle ___________________________________________________________________________ Function Returns the number of expanded memory pages allocated to a specific EMM handle. Syntax unsigned getpagesownedbyhandle(unsigned handle, unsigned *pagesowned) Result type Returns a return code of 0 if EMM software is successful. Remarks An EMM handle never has zero pages of memory allocated to it. Expanded Memory Test Program #include "teglsys.h" unsigned emm_handle, page_frame_base_address, pages_needed, physical_page, logical_page, offset, error_code, pages_ems_available, total_handle_count, pages_owned, total_ems_pages, available_ems_pages; char version_number[5], Error_String[80], verify; char *dataptr; void error(char *error_message, int error_number) { printf("%sn", error_message); printf(" Error_Number = %Xn", error_number); printf("EMS test program aborting.n"); Programmer's Reference Guide - 209 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager exit(1); } void main() { /* * Determine if the Expanded Memory Manager is installed, If not, * then terminate 'main' with an ErrorLevel code of 1. */ if (!(emminstalled())) { printf("The LIM Expanded Memory Manager is not installed.n"); exit(1); } /* Get the version number and display it */ error_code = getversionnumber(version_number); if (error_code != 0) error("Error trying to get the EMS version number ", error_code); else printf("LIM Expanded Memory Manager, version %s is ready for " "use.nn", version_number); /* * Determine if there are enough expanded memory pages for this * application. */ pages_needed = 1; error_code = emspagesavailable(&total_ems_pages, &available_ems_pages); if (error_code != 0) error("Error trying to determine the number of EMS pages " "available.", error_code); printf("There are a total of %d expanded memory pages present in this" " system.n", total_ems_pages); printf(" %d of those pages are available for your usage.nn", available_ems_pages); /* * If there is an insufficient number of pages for our application, * then report the error and terminate the EMS test program */ if (pages_needed > available_ems_pages) { Programmer's Reference Guide - 210 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager sprintf(Error_String, "We need %d EMS pages. There are not that " "many available.", pages_needed); error(Error_String, error_code); } /* Allocate expanded memory pages for our usage */ error_code = allocateexpandedmemorypages(pages_needed, &emm_handle); sprintf(Error_String, "EMS test program failed trying to allocate %d" " pages for usage.", pages_needed); if (error_code != 0) error(Error_String, error_code); printf("%d EMS page(s) allocated for the EMS test program.nn", pages_needed); /* * Map in the required logical pages to the physical pages given to * us, in this case just one page */ logical_page = 0; physical_page = 0; error_code = mapexpandedmemorypages(emm_handle, logical_page, physical_page); if (error_code != 0) error("EMS test program failed trying to map logical pages onto" " physical pages.", error_code); printf("Logical Page %d successfully mapped onto Physical Page " "%dnn", logical_page, physical_page); /* Get the expanded memory page frame address */ error_code = getpageframebaseaddress(&page_frame_base_address); if (error_code != 0) error("EMS test program unable to get the base Page Frame " "Address.", error_code); printf("The base address of the EMS page frame is - " "%X.nn",page_frame_base_address); /* Get Handle Count and the number of pages for our handle */ error_code = gethandlecountused(&total_handle_count); if (error_code != 0) error("EMS test program unable to get the Handle Count Used.", error_code); error_code = getpagesownedbyhandle(emm_handle, &pages_owned); if (error_code != 0) error("EMS test program unable to get the number of pages Owned " Programmer's Reference Guide - 211 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager "by handle.", error_code); printf("The Total Handle Count is %d and the number of Pages owned is" " %d.nn", total_handle_count, pages_owned); /* Write a test pattern to expanded memory */ for (offset = 0; offset <= 16382; offset++) pokeb(page_frame_base_address, offset, offset % 256); /* Make sure that what is in EMS memory is what we just wrote */ printf("Testing EMS memory.n"); offset = 1; verify = 1; while ((offset <= 16382) && verify) { if (peekb(page_frame_base_address, offset) != offset % 256) verify = 0; offset++; } /* If it isn't report the error */ if (!verify) error("What was written to EMS memory was not found during memory" " verification test.", 0); printf("EMS memory test successful.nn"); /* * Return the expanded memory pages given to us back to the EMS * memory pool before terminating our test program */ error_code = deallocateexpandedmemorypages(emm_handle); if (error_code != 0) error("EMS test program was unable to deallocate the EMS pages in" " use.", error_code); printf("%d page(s) deallocated.nn", pages_needed); printf("EMS test program completed.n"); } A RAM Disk Driver Expanded Memory (EMS), in its architecture of multiple pages, is limited in its use as a direct access heap without complex programming. However, Programmer's Reference Guide - 212 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager one of the simplest ways to take advantage of EMS, is to create a EMS ram disk. The following EMS RAM Disk functions provides the basics for storing and retrieving a file from EMS memory. ___________________________________________________________________________ emsopen ___________________________________________________________________________ Function Opens an EMS Ram Disk file. Syntax emsfile emsopen(unsigned minimumpages) Result type EMSOpen returns a structure type of EMSFile. Remarks EMSFile is predeclared as follows: typedef struct emsblock { emsblockptr nextblockptr; unsigned handle; /* Multiple handles */ unsigned emspage;/* Pages allocated */ } emsblock; typedef struct emsfilerec { unsigned pageoffset; /* current offset within page */ unsigned baseaddress; unsigned long emsposition; unsigned totalpages; /* Total number of 16k pages */ emsblockptr rootblkptr; } emsfilerec; The baseaddress and pageoffset forms the pointer to the physical expanded memory page. The emsposition field is the current RAM disk file position. totalpages is the total number of expanded memory pages allocated for this EMS Ram file. The rootblkptr points to the first EMS Block pointer. The minimumpages parameter specifies the initial allocation, however if more pages are required, as you write to the EMS Ram file, pages are automatically Programmer's Reference Guide - 213 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager allocated as needed. Additional EMS handles and Pages information are stored in separate EMS Block records and are chained together. ems_status will return a 0 if the EMS ram file is allocated successfully; otherwise, it will return a nonzero error code. See also emsclose ___________________________________________________________________________ emsseek ___________________________________________________________________________ Function Moves the current position of an EMS RAM file to a specified byte component. Syntax void emsseek(emsfile emsramfile,unsigned long position) Remarks emsramfile is the structure type returned by emsopen, and position is an expression of type unsigned long. The current EMS Ram file position is moved to the offset position. In order to expand the expanded memory pages allocated, it is possible to emsseek any size beyond the last byte; thus emsseek(myramfile, 98304) will automatically allocate, if required, a total of 6 pages. ems_status will return a 0 if the operation was successful; otherwise, it will return a nonzero error code. Restrictions EMS Ram file must be open. See also emsblockwrite, emsblockread, emsopen, emsclose ___________________________________________________________________________ emsblockwrite ___________________________________________________________________________ Programmer's Reference Guide - 214 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager Function Writes the information pointed to by the Buffer pointer to the EMS Ram file. Syntax void emsblockwrite(emsfile emsramfile,char *buffer,unsigned long bytestowrite) Remarks emsramfile is the structure type returned by sh EMSOpen, buffer is any char * type, and bytestowrite is an expression of type unsigned long. emsblockwrite writes bytestowrite bytes to the emsramfile. bytestowrite may be greater than (64k). emsblockwrite will automatically allocate additional EMS Memory pages if the current EMS ram file position plus bytestowrite exceeds the currently allocated expanded memory pages. The current EMS Ram file position is advanced by bytestowrite on completion of emsblockwrite. ems_status will return a 0 if the operation was successful; otherwise, it will return a nonzero error code. Restrictions EMS Ram file must be open. See also emsseek, emsblockread, emsopen, emsclose ___________________________________________________________________________ emsblockread ___________________________________________________________________________ Function Reads from the EMS Ram file to memory pointed to by the buffer pointer. Syntax void emsblockwrite(emsfile emsramfile,char *buffer,unsigned long bytestowrite) Remarks emsramfile is the structuretype returned by sh emsopen, buffer is any char * type, and bytestoread is an expression of type long. emsblockread reads bytestoread bytes to the Programmer's Reference Guide - 215 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager memory area pointed to by buffer. bytestoread may be greater than (64k). emsblockread will read past the end of Ram file and automatically allocate additional EMS Memory pages if the current EMS Ram file position plus bytestoread exceeds the currently allocated expanded memory pages. The current EMS Ram file position is advanced by bytestoread on completion of emsblockread. ems_status will return a 0 if the operation was successful; otherwise, it will return a nonzero error code. Restrictions EMS Ram file must be open. See also emsblockwrite, emsseek, emsopen, emsclose ___________________________________________________________________________ emsclose ___________________________________________________________________________ Function Close an Open EMS Ram file. Syntax void emsclose(emsfile emsramfile) Remarks emsramfile is the structure type returned by sh emsopen. ems_status will return a 0 if the operation was successful; otherwise, it will return a nonzero error code. See also emsopen Virtual Disk Heap A virtual Disk Heap allows you to simulate a heap using a sequential file. Allocating and freeing space within the Virtual Disk Heap are automatically maintained, with all the flexibility of a real memory heap manager and the unlimited space of a hard disk. The virtual Disk Heap manager has the ability to reuse free space, as well as merging adjacent free space fragments. Programmer's Reference Guide - 216 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager In addition the virtual disk heap (disk mode) can be used as a simple graphical image database manager. The stored images may be retrieved later by referring to a unique signature that you provide. ___________________________________________________________________________ vdskopenheapfile ___________________________________________________________________________ Function Opens a heap file on disk. Syntax vdskfile vdskopenheapfile(char *vdskfilename,unsigned vdskattribute) Result type vdskopenheapfile returns a structure type vdskfile. Remarks vdskfilename is a char * expression that contains the name of heap file and vdskattribute is the attribute that is associated with the file. The following vdskattribute enum are declared: enum { vdskreadwrite = 1}; enum { vdsktemporary = 2}; vdskopenheapfile will create a new file if the file does not exist. If vdskreadwrite is specified, the file is not erased when the file is closed. if vdskattribute is set to vdsktemporary, the file is automatically erased when the file is closed. vdskfile is declared as follows: typedef struct vdskfreerecord *vdskfreeptr; typedef struct vdskfreerecord { vdskfreeptr nextvdskfree; unsigned long startblock; unsigned long endblock; signate signature; char blockfree; } vdskfreerecord; typedef struct vdskfilerecord *vdskfile; Programmer's Reference Guide - 217 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager typedef struct vdskfilerecord { vdskfreeptr vdskfreeptrchain; unsigned long vdsktopoffile; unsigned vdskattribute; unsigned long vdskpacketsave; char *vdskfilename; char emstype;/* Selector */ union v { int vdskheapfile; emsfile vemsheapfile; } v; } vdskfilerecord; vdskfreeptrchain maintains a complete list of all blocks that are allocated and freed. Information regarding each block are stored in a chain of vdskfreerecord. The vdsktopoffile is the position of the end of the heap file. If there are no free space fragments before the end of the heap file to satisfy the requested block size, space is allocated starting at vdsktopoffile. vdskattribute is the passed parameter when the file was opened. The emstype sets the variant portion to either disk or ems memory. startblock and endblock is the starting and ending address of the allocated or freed block, respectively. signature is a unique type of a 4 character string that can be used as a search string to locate an address of a block. blockfree indicates whether the block is allocated or free. vdskstatus will return a 0 if the operation was successful; otherwise, it will return a nonzero error code. See also vemsopenheapfile, vdskcloseheapfile ___________________________________________________________________________ vemsopenheapfile ___________________________________________________________________________ Function Opens a heap file in EMS. Programmer's Reference Guide - 218 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager Syntax vdskfile vemsopenheapfile(int initialalloc) Result type vemsopenheapfile returns a variable of type vdskfile. Remarks vemsopenheapfile creates the same structure as vdskopenheapfile, with the emstype set to ems memory. vdskstatus will return a 0 if the ems operation was successful; otherwise, it will return a nonzero error code. See also vdskopenheapfile, vdskcloseheapfile ___________________________________________________________________________ vdskgetmem ___________________________________________________________________________ Function Allocates a block within the virtual heap memory and returns a virtual heap address. Syntax unsigned long vdskgetmem(vdskfile vdskpacket, unsigned long heapsize,char *signature) Result type vdskgetmem returns a virtual heap address of long. Remarks vdskstatus will return a 0 if the virtual heap allocation was successfull; otherwise, it will return a nonzero error code. Restrictions The Virtual Heap memory must be opened. See also vdskfreemem, vdskwriteheapdata, vdskreadheapdata ___________________________________________________________________________ vdskfreemem ___________________________________________________________________________ Programmer's Reference Guide - 219 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager Function Frees the virtual heap memory pointed to by the VDskHeapPtr. Syntax void vdskfreemem(vdskfile vdskpacket,unsigned long vdskheapptr) Remarks vdskpacket is the structure type returned by vemsopenheapfile or vdskopenheapfile. The vdskheapptr must be the virtual disk pointer from vdskgetmem. vdskstatus will return a 0 if the virtual heap de-allocation was successful; otherwise, it will return a nonzero error code. Restrictions The Virtual Heap memory must be opened. See also vdskgetmem, vdskwriteheapdata, vdskreadheapdata ___________________________________________________________________________ vdskwriteheapdata ___________________________________________________________________________ Function Writes the data from memory pointed to by the DataPtr to an allocated virtual heap memory vdskheapptr. Syntax void vdskwriteheapdata(vdskfile vdskpacket,char far *dataptr,unsigned long vdskheapptr) Remarks vdskpacket is the structure type returned by vemsopenheapfile or vdskopenheapfile. The dataptr is of a pointer type that points to a memory buffer that will be written out to the virtual heap. The vdskheapptr must be the virtual heap pointer created from vdskgetmem. vdskstatus will return a 0 if writing to the virtual heap was successful; otherwise, it will return a nonzero error code. Restrictions The Virtual Heap memory must be opened. See also Programmer's Reference Guide - 220 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager vdskgetmem, vdskfreemem, vdskreadheapdata ___________________________________________________________________________ vdskreadheapdata ___________________________________________________________________________ Function Reads the data from the virtual heap memory to a memory area pointed to by the DataPtr. Syntax void vdskreadheapdata(vdskfile vdskpacket,char far *dataptr,unsigned long vdskheapptr) Remarks vdskpacket is the structure type returned by vemsopenheapfile or vdskopenheapfile. The dataptr is of a pointer type that points to a memory buffer that will be overwritten by the transfer of data from the virtual heap. The vdskheapptr must be the virtual heap pointer created from vdskgetmem. vdskstatus will return a 0 if writing to the virtual heap was successful; otherwise, it will return a nonzero error code. Restrictions The Virtual Heap memory must be opened. See also vdskgetmem, vdskfreemem, vdskwriteheapdata ___________________________________________________________________________ vdskcloseheapfile ___________________________________________________________________________ Function Closes a virtual heap. Syntax void vdskcloseheapfile(vdskfile vdskpacket) Remarks vdskpacket is the structure type returned by vemsopenheapfile or vdskopenheapfile. vdskstatus will return a 0 if the virtual heap Programmer's Reference Guide - 221 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager operation was successful; otherwise, it will return a nonzero error code. See also vemsopenheapfile, vdskopenheapfile The Virtual Heap Error Function The vdskerror variable allows you to install a virtual heap error function, which gets called whenever the TEGL heap manager cannot complete an allocation request. vdskerror is a pointer that points to a function with the following header: int myvirtualerr (unsigned long heapsize) The virtual heap error function is installed by assigning its address to the vdskerror variable: vdskerror = myvirtualerr; The virtual heap error function gets called whenever any virtual function calls is unable to complete the request. The code parameter contains a code indicating which virtual heap function is in error. Check VDSKStatus to determine the severity of the error. The standard virtual heap error function is set to return to the calling procedure. If you are using the Virtual memory manager (next section), use the virtual memory error function rather then this error function to intercept virtual errors. The virtual memory manager relies on the standard q return to the calling procedure to check vdskstatus to indicate whether to write to EMS or disk file. The Virtual Memory Manager The virtual memory manager is in constant use by TEGL windows to provide memory extensions for graphical images. Your program may use the virtual memory functions as an external heap, with the restriction that you do close the virtual memory file. The following virtual memory functions will automatically select the Programmer's Reference Guide - 222 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager storage medium when moving data to virtual memory. The data is moved to expanded memory if adequate space can be found, otherwise the data is moved to one of the mass storage mediums. Both storage medium (EMS and Hard disk) are used if available. ___________________________________________________________________________ useharddisk ___________________________________________________________________________ Function This function forces the virtual memory manager to use the hard disk as virtual memory, even if EMS is available. Syntax Macro void useharddisk(char yesno) Remarks if the yesno is 1, then the virtual memory manager will ignore the installed EMS, and only use the hard disk. ___________________________________________________________________________ MoveFromVirtual procedure VIRTMEM ___________________________________________________________________________ Function Moves a block of data from virtual back to normal memory. Syntax void movefromvirtual(char far * dataptr, unsigned long virtualheapptr) Remarks The dataptr is any memory block. virtualheapptr is of the type unsigned long, which is the address supplied by movetovirtual. vdskstatus will return a 0 if the virtual memory operation was successful; otherwise, it will return a nonzero error code. See also movetovirtual, freevirtual Programmer's Reference Guide - 223 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager ___________________________________________________________________________ movetovirtual ___________________________________________________________________________ Function Moves a block of data from memory to virtual memory. Syntax unsigned long movetovirtual(char far *dataptr,unsigned long heapsize) Result type movetovirtual returns a unsigned long type, which is a physical address of the virtual block. Remarks The dataptr is any memory block allocated by cgetmem or fgetmem. heapsize is of the type unsigned long, which is the size of the memory block that you are moving to virtual memory. movetovirtual will automatically allocate ems memory pages and open any virtual memory files (if needed) if this is the first time call to this procedure. vdskstatus will return a 0 if the virtual memory operation was successful; otherwise, it will return a nonzero error code. See also movefromvirtual, freevirtual ___________________________________________________________________________ freevirtual ___________________________________________________________________________ Function Frees the virtual memory back to the virtual memory pool for reuse. Syntax void freevirtual(unsigned long virtualheapptr) Remarks virtualheapptr is of the type unsigned long, which is the address supplied by movetovirtual. Programmer's Reference Guide - 224 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager vdskstatus will return a 0 if the virtual memory operation was successful; otherwise, it will return a nonzero error code. See also movetovirtual, movefromvirtual ___________________________________________________________________________ cmaxavail ___________________________________________________________________________ Function Returns the size of the largest block available in the upper heap. Syntax unsigned long cmaxavail(void) ___________________________________________________________________________ virtualmemused ___________________________________________________________________________ Function Returns the amount of virtual memory allocated. Syntax unsigned long virtualmemused(void) Remarks This is the total of virual memory allocated. On some systems this can be a combination of both EMS and Disk memory. The Virtual Memory Error Function The virtualerror variable allows you to install a virtual memory error function, which gets called whenever the virtual memory manager cannot complete a virtual function request. virtualerror is a pointer that points to a function with the following header: int myvirtmemerr (unsigned code) Programmer's Reference Guide - 225 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager The virtual memory error function is installed by assigning its address to the VirtualError variable: vdskerror := myvirtmemerr; The virtual memory error function gets called whenever any virtual function calls is unable to complete the request. The code parameter contains a code indicating which virtual heap function is in error. Check vdskstatus to determine the severity of the error. The standard virtual memory error function is set to return to the calling function. Resolving Fragments The memory used by the heap is a dynamic and volatile part of your program. Memory is constantly allocated and de-allocated by the window manager along with allocation of dynamic variables, free space structures, frame structures, mouse click structures, etc. Although the virtual memory manager will provide almost unlimited windows, the concept is still limited by the number of window structures that will fit in memory and whether the memory is contiguous or fragmented by allocated memory not under the control of the virtual memory manager. Fragmentation occurs, when free memory blocks are separated by allocated blocks. Since certain allocated memory blocks cannot be moved or de-allocated, fragmentation can cut down the largest block size available from the heap. Without a proper control on memory fragmentation, an out of space error can still occur even when the virtual memory manager pages out all window images. In order for the virtual memory Manager to provide large contiguous memory on the heap, two memory managers are used to partition the far heap memory. The normal Turbo C heap manager is replaced with cgetmem to allocate simple memory blocks like frame information and virtual pointer information. The second, is fgetmem, used by the window manager to allocated large image buffers. The function ReserveHugeMinimum partitions the far heap memory into two parts by allocating a single byte between the minimum and upper memory. Normal allocations using cgetmem will default to the lower areas. cgetmem will use the upper area when all lower memory area is used, thus Programmer's Reference Guide - 226 - TEGL Windows Toolkit Chapter 13 - Virtual Memory Manager the lower memory area is not a restriction. fgetmem will only allocate memory from the upper areas. ReserveHugeMinimum provides an elegant solution, that allows normal allocation with cgetmem and volatile fgetmem to coexist. ___________________________________________________________________________ reservehugeminimum ___________________________________________________________________________ Function Partition the heap memory into lower and upper areas to reduce fragmentation. Syntax Macro void reservehugeminimum(unsigned long minsize) Remarks minimumsize is of the type unsigned long, which is the size calculated by adding (60 bytes for a window structure) + the average mouse click and key clicks areas per window (20 bytes per each defined click) multiplied by the maximum number of window records opened at the same time + 4000 bytes (overhead for the virtual memory manager) plus any heap memory requirements by the application. You are not expected to calculate the exact minimumsize, but as a general rule of thumb, it seems that 12k is effective for most applications. Programmer's Reference Guide - 227 - TEGL Windows Toolkit Chapter 14 - Sizing and Sliders Sizing and Sliding The chapter has the procedures and functions that give the core for resizing frames and attachings sliders to them. A slider is a moveable switch. They are quite often used to indicate up and down or left to right scrolls (as in a text editor). They can be attached to a window but are seperate, that is, they must be disposed of seperately. Resizing frames adds a degree of complexity to maintaining frames in that the contents of the frame are lost when it is resized. Consequently, you need to code an event that specifically redraws a frame after resizing. Resizable frames with slider bars require more work. It is up to the programmer to dispose of and then reattach new sliders to a frame after a resize. This presumably is all done within the event that redraws the window. This is not impossible, just careful thought is required when making these kinds of frames. The results will speak for themselves. ___________________________________________________________________________ defineresizeclickarea ___________________________________________________________________________ Function Sets a mouse click area for resizing a frame. Declaration void defineresizeclickarea(imagestkptr ifs, unsigned x, unsigned y, unsigned x1, unsigned y1, callproc resizeproc); Remarks The resizeproc must be defined. You cannot pass a NULL pointer. When a frame is resized its image is disposed and must be redrawn. See also defineresizeminmax. Example defineresizeclickarea(ifs,1,1,10,6,redraweditor); Programmer's Reference Guide - 228 - TEGL Windows Toolkit Chapter 14 - Sizing and Sliders ___________________________________________________________________________ defineresizeminmax ___________________________________________________________________________ Function Sets the minimum and maximum that a frame can be resized to. Declaration void defineresizeminmax(imagestkptr ifs, unsigned minw, unsigned minh, unsigned maxw, unsigned maxh); Remarks minw is the minimum width the frame is allowed if resized. minh is the minimum height, maxw is the maximum width, and maxh is maximum height. Values are in pixels. See also defineresizeclickarea. Example defineresizeminmax(ifs,200,100,400,200); ___________________________________________________________________________ definesliderarea ___________________________________________________________________________ Function Defines slider area. Declaration void definesliderarea(imagestkptr ifs, unsigned x, unsigned y, unsigned x1, unsigned y1, unsigned minx, unsigned miny, unsigned maxx, unsigned maxy, callproc slideaction); Remarks ifs is the frame the slider is attached to. x,y, x1, y1 is the slider click area. minx, miny, maxx, maxy are the bounds the slider can be moved in. Coordinates are frame relative. slideaction is the event that is called when the slider is moved. Programmer's Reference Guide - 229 - TEGL Windows Toolkit Chapter 14 - Sizing and Sliders The msclickptr that is passed to slideaction contains the new slider position. These coordinates can be used to determine the correct action to taken. Restrictions This procedure only sets the area for the slider and its bounds. It is up to the programmer to draw the slider bar and the slider. The slider bar must be drawn before the call to definesliderarea. Then after this draw the slider. The toolkit will look after moving the slider once it has been drawn. See also setslidepostion Example ___________________________________________________________________________ dropsliders ___________________________________________________________________________ Function Removes all sliders from a frame. Declaration void dropsliders(imagestkptr ifs); Remarks dropsliders should be called before you drop a frame or resize it. Restrictions See also Example dropsliders(ifs); ___________________________________________________________________________ findsliderfs ___________________________________________________________________________ Programmer's Reference Guide - 230 - TEGL Windows Toolkit Chapter 14 - Sizing and Sliders Function Finds a slider on a frame. Declaration sliderptr findsliderfs(imagestackptr ifs, msclickptr ms); Remarks Returns the sliderptr associated with ms on the frame. This can be used from within an event that is called when a slider is moved. With the SliderPtr you can determine the relative position of the slider without having to examine any other variables. Restrictions See also Example ___________________________________________________________________________ resizeframe ___________________________________________________________________________ Function Allocates a new buffer for a frame. Declaration void resizeframe(imagestkptr ifs, unsigned x, unsigned y, unsigned x1, unsigned y1); Remarks x, y, x1, y1 are the new coordinates of the frame. Restrictions The frame image is hidden then disposed. See also defineresizeminmax Example ___________________________________________________________________________ Programmer's Reference Guide - 231 - TEGL Windows Toolkit Chapter 14 - Sizing and Sliders selectandmoveframe ___________________________________________________________________________ Function An event that allows the frame to be moved. Declaration unsigned selectandmoveframe(imagestkptr ifs, msclickptr ms); Remarks Note that this is an event. You would not directly call it but rather would pass it with a definemouseclickarea. See also definemouseclickarea. Example /* the top 10 pixels across the frame ifs is set to SelectAndMoveFrame */ definemouseclickarea(ifs,0,0,ifs->x1,10,TRUE, selectandmoveframe,MSCLICK); ___________________________________________________________________________ setslideposition ___________________________________________________________________________ Function Moves a slider to a new position. Declaration void setslideposition(imagestkpointer ifs, unsigned x, unsigned y); Remarks x,y are relative coordinates within the frame and must be within the slider bar. See also definesliderarea. Programmer's Reference Guide - 232 - TEGL Windows Toolkit Miscellaneous Functions Miscellaneous Functions ___________________________________________________________________________ ___________________________________________________________________________ checkctrlbreak ___________________________________________________________________________ Function Checks task handler. Syntax void checkctrlbreak(void); Remarks Normally this routine does not have to be called, but if you have section of code that is going through a long loop you should insert it there. If your program has events that are activated after a certain number of timer ticks have passed then a call to checkctrlbreak will allow their processing. The TEGL Windows Toolkit does not process timer interrupt tasks directly, rather a flag is set and the task is performed when it is safe (ie. no frames are being updated and no memory swaps are begin processed). Example long x; for (x = 1;x < 20000000; x++) /* do your stuff */ checkctrlbreak(); /* allow processing of other tasks */ ___________________________________________________________________________ checkctrlbreakfs ___________________________________________________________________________ Programmer's Reference Guide - 233 - TEGL Windows Toolkit Miscellaneous Functions Function Sets an event to call when Ctrl-Break is pressed. Syntax Macro void checkctrlbreakfs(callproc p); Remarks P is an event and works like any other. You can determine within it what processing should take place (Halt, Continue, Close files, etc..). Example see inittegl in tegleasy. ___________________________________________________________________________ droptimertick ___________________________________________________________________________ Function Removes an event set with SetTimerTick. Syntax void droptimertick(unsigned ticks, callproc p); Remarks both ticks and p must be identical to the orginal call for the event to be removed. See also settimertick. Example droptimertick(18,backgroundclock); ___________________________________________________________________________ nilunitproc ___________________________________________________________________________ Function Programmer's Reference Guide - 234 - TEGL Windows Toolkit Miscellaneous Functions A place holder for events that have not been coded. Syntax unsigned nilunitproc(imagestkptr ifs, msclickptr ms); Remarks nilunitproc can be used wherever an event handler is called for. This can be a place holder or it can be where event is desired but a parameter is required. Example { -- a line in a menu that is never selected or active } defineoptions(filem,'--',FALSE,nilunitproc); ___________________________________________________________________________ overlaparea ___________________________________________________________________________ Function Returns the area that is occupied by two sets of coordinates. Syntax char overlaparea(unsigned ax, unsigned ay, unsigned ax1, unsigned ay1, unsigned bx, unsigned by, unsigned bx1, unsigned by1, unsigned *cx, unsigned *cy, unsigned *cx1, unsigned *cy1); Remarks a and b coodinates are the areas to test. If they overlap then the area is return in the c coordinates and the function returns true, otherwise the function returns false and the c coordinates are undetermined. This is an advanced function that normally would not be used. ___________________________________________________________________________ settimertick ___________________________________________________________________________ Programmer's Reference Guide - 235 - TEGL Windows Toolkit Miscellaneous Functions Function Sets an event to be called periodically. Syntax void settimertick(unsigned ticks, callproc p, imagestkptr ifs, msclickptr ms); Remarks Ticks is how many timer ticks to wait before begin called. p is the event to call. ifs and ms are passed to p. See also droptimertick. Example settimertick(18,backgroundclock,NULL,NULL); Programmer's Reference Guide - 236 - TEGL Windows Toolkit Graphics Library - tgraph TGraph ___________________________________________________________________________ The tgraph module provides a subset of the functions in the graphics.lib unit provided with Turbo C. tgraph does not have to be used if you are using Turbo C. If your program requires elaborate graphics drawing and painting then graphics.lib is needed. If, however, your graphics need are simpler then tgraph may provide all that is needed. If this is the case your program can be as much as 25K smaller by using tgraph exculsively. See the appendix Conditional Compilation for directions on building the toolkit without using graphics.lib. If you are programming with Microsoft's C or Quick C then tgraph is necessary. Depending on the defines in the file teglcond.h (see the appendix Conditional Compilation) tgraph acts as stand-alone or maps graphics calls to the equivalent routine in graphics.lib. Both Turbo C and Microsoft C's provide the file (it graphics.lib but they are not compatible. TEGL Windows Toolkit tgraph module uses the naming conventions for graphics.lib in Turbo C. When using Turbo C and tgraph be sure NOT to specify the graphics library option in the integrated environment. For the command line compiler do not include graphics.lib in the link list. ___________________________________________________________________________ Bar ___________________________________________________________________________ Function Draws a bar using the current fill style and color. Syntax Bar(x1, y1, x2, y2: Integer); Remarks Draws a filled in bar using the pattern and color defined by SetFillStyle or SetFillPattern. See also SetFillStyle, SetFillPattern ___________________________________________________________________________ closegraph ___________________________________________________________________________ Programmer's Reference Guide - 237 - TEGL Windows Toolkit Graphics Library - tgraph Function Shuts down the graphics system. Syntax closegraph; Remarks The screen mode is restored to the original mode before graphics were initialized. ___________________________________________________________________________ detectgraph ___________________________________________________________________________ Function Detects graphics hardware. Syntax void far detectgraph(int far *graphdriver, int far graphmode); Remarks Returns the detected driver and mode value that can be passed to initgraph which will change to graphics mode. If no graphics hardware is found or the graphics hardware is not supported then a call to graphresult will return a value of -2 (grNotDetected). See also initgraph, graphresult ___________________________________________________________________________ getbkcolor ___________________________________________________________________________ Function Returns the current background color. Syntax int far getbkcolor(void); Remarks Background colors can range from 0 to 15. See also getcolor, setbkcolor, setcolor Programmer's Reference Guide - 238 - TEGL Windows Toolkit Graphics Library - tgraph ___________________________________________________________________________ getcolor ___________________________________________________________________________ Function Returns the color value passed to the previous call to setcolor. Syntax int far getcolor(void); Remarks Drawing colors can range from 0 to 15. See also setcolor ___________________________________________________________________________ getfillpattern ___________________________________________________________________________ Function Returns the last fill pattern set by the last call to setfillpattern. Syntax void far getfillpattern(char far *pattern); Remarks Copies the user-defined fill pattern set by setfillpattern into the area pointed to by pattern. It must be an area of 8 bytes. The following pattern definition would create a solid fill. char solid[8] = 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff; See also setfillpattern, getfillsettings ___________________________________________________________________________ getgraphmode ___________________________________________________________________________ Programmer's Reference Guide - 239 - TEGL Windows Toolkit Graphics Library - tgraph Function Returns the current graphics mode. Syntax int far getgraphmode(void); Remarks Returns the current graphics mode set by initgraph or setgraphmode. See also detectgraph, initgraph, restorecrtmode, setgraphmode ___________________________________________________________________________ getmaxx ___________________________________________________________________________ Function Returns the pixel width (minus 1) of the current graphics driver and mode. Syntax int far getmaxx(void); Remarks getmaxx can be used to determine the boundaries of the screen. See also getmaxy, getx, gety ___________________________________________________________________________ getmaxy ___________________________________________________________________________ Function Returns the pixel height (minus 1) of the current graphics driver and mode. Syntax int far getmaxy(void); Remarks getmaxy can be used to determine the boundaries of the screen. See also getmaxx, getx, gety Programmer's Reference Guide - 240 - TEGL Windows Toolkit Graphics Library - tgraph ___________________________________________________________________________ gettextsettings ___________________________________________________________________________ Function Returns the current text settings. Syntax void far gettextsettings(struct textsettingstype far *textinfo); Remarks textsettingstype contains fields for the font, direction, size and justification that was set by settextstyle and settextjustify. See also settextjustify, settextstyle ___________________________________________________________________________ graphresult ___________________________________________________________________________ Function Returns the error code for the last graphics operation. Syntax int far graphresult(void); Remarks graphresult is reset to zero after it has been called. The user may want to store it into a temporary variable before testing it. ___________________________________________________________________________ imagesize ___________________________________________________________________________ Function Returns the number of bytes required to store a rectangular region of the screen. Syntax unsigned far imagesize(int x1, int y1, int x2, int y2); Programmer's Reference Guide - 241 - TEGL Windows Toolkit Graphics Library - tgraph Remarks x1,y1,x2,y1 defines the area on the screen. ___________________________________________________________________________ initgraph ___________________________________________________________________________ Function Initializes the graphics system and sets the hardware to graphics mode. Syntax void far initgraph(int far *graphdrive, int far *graphmode, char far *driverpath); Remarks If graphdriver is equal to 0 (DETECT) then a call is made to detectgraph. If supported hardware is detected then the graphics system is initialized and a graphics mode is selected. The parameter driverpath is provided for compatibility with graphics.lib, it is not used, all drivers are linked in. If you are using one of the Microsoft C compilers and a hurcules display then the program MSHerc.com must be run first. See also detectgraph, closegraph ___________________________________________________________________________ line ___________________________________________________________________________ Function Draws a line from x1, y1 to x2, y2. Syntax void far line(int x1, int y1, int x2, int y2); Remarks Draws a line in the color set by setcolor Programmer's Reference Guide - 242 - TEGL Windows Toolkit Graphics Library - tgraph ___________________________________________________________________________ outtextxy ___________________________________________________________________________ Function Sends a string to the screen. Syntax void far outtextxy(int x, int y, char far* textstring); Remarks textstring is output at the screen location x,y. outtextxy uses the options set by settextjustify. See also settextjustify, gettextsettings ___________________________________________________________________________ rectangle ___________________________________________________________________________ Function Draws a rectangle using the current color. Syntax void far rectangle(int x1, int y1, int x2, int y2); Remarks x1,y1 define the upper left corner of the rectangle, and x2,y2 define the lower right corner. See also setcolor ___________________________________________________________________________ restorecrtmode ___________________________________________________________________________ Function Restore the screen mode. Syntax restorecrtmode; Remarks Restore the screen mode to its original state before Programmer's Reference Guide - 243 - TEGL Windows Toolkit Graphics Library - tgraph graphics was initialized. See also detectgraph, initgraph ___________________________________________________________________________ setbkcolor ___________________________________________________________________________ Function Sets the backgound color. Syntax void far setbkcolor(int color); Remarks Background colors may range from 0 to 15. See also getbkcolor,setcolor ___________________________________________________________________________ setcolor ___________________________________________________________________________ Function set the drawing color. Syntax setcolor(int color); Remarks Drawing colors may range from 0 to 15. See also getcolor ___________________________________________________________________________ setfillpattern ___________________________________________________________________________ Function Selects a user-defined fill pattern. Syntax void far setfillpattern(char far *upattern, int color); Programmer's Reference Guide - 244 - TEGL Windows Toolkit Graphics Library - tgraph Remarks Sets the pattern and color for all filling done by bar. See also getfillpattern, setfillstyle ___________________________________________________________________________ setfillstyle ___________________________________________________________________________ Function Sets the fill pattern and color. Syntax void far setfillstyle(int pattern,int color); Remarks Set the pattern and color for all filling done by bar. There are 12 fill patterns available. See also getfillsettings ___________________________________________________________________________ settextjustify ___________________________________________________________________________ Function Sets text justification values used by outtextxy and outtegltextxy. Syntax settextjustify(int horiz, int vert); Remarks The default justification settings are settextjustify( lefttext, toptext). See also gettextsettings, outtextxy Programmer's Reference Guide - 245 - TEGL Windows Toolkit APPENDICES Appendix A - Overlapping Graphics ___________________________________________________________________________ There are many methods in creating and managing overlapping windows, however the end result to the user must be in the context of windows that form independent layers on a single display. This section discusses the method that is used with the TEGL Windowing Manager. Video Buffers The video buffer is a block of memory where displayable data is stored. A program may read and write to the video buffer in the same way it accesses any other memory. The video display circuitry updates the screen by continually reading the data in the video buffer and translating the bit information to the screen. Each group of bits in the video buffer specifies the color and brightness of a particular location on the screen. A particular location on the screen is known as a pixel. If a program changes the contents of the video buffer, the screen reflects the change immediately. Because you have control over each pixel in the displayed image, you can construct complex geometric images, fill arbitrary areas of the screen with blends of colors, or create animated images that moves across the screen. We may think of windows as multiple video buffers, the distinction is that, with the TEGL Windows Toolkit, only 1 video buffer is used. To create a window effect, we must physically copy and move display data to and from a single video buffer, overlaying the images as we would layout images on paper. Windows Windows are simply predefined rectangular areas of the screen. A window manager is a coordinator that ensures that images related to a window are saved (stored in memory) before other overlapping images writes to the screen. When a window is closed, the underlying image is copied back to screen video buffer. The basis of a window manager is the copying and restoring of multiple areas of the screen. Frames Programmer's Reference Guide - 246 - TEGL Windows Toolkit APPENDICES An EGA video has a maximum resolution of 640 pixels horizontal by 350 pixels. The coordinates are specified as (x,y) and (x1,y1), where x and y are the horizontal and vertical position respectively. The position is relative to upper left coordinate which has a coordinate value of (0,0). (x,y) +---------+ |(y) | || | || | |* | | | |(x)----->| +---------+ (x1,y1) A Frame Stack A frame stack is a list with each entry representing a screen area. Each entry contains information and data that is required by the window manager to coordinate the overlaps between frames. The order of the list is in the same order as the frames are stacked on the screen. A Simple Window Manager This section talks about creating a simple window manager. We will use the following example to see how we can update frame (A) independent of the other 3 frames. The following frames have called PUSHIMAGE to save the underlying graphics. +----------------+ +---------+--+ | | | | | |--+ | | |B | A | | D |--+ | | | | | |--+ | | |C | | | |--+ | | | | +---------+--+ | | | +----------------+ Programmer's Reference Guide - 247 - TEGL Windows Toolkit APPENDICES In order for Frame (A) to be updated, the image for Frame (D) is saved, and Frame (D) is erased from the screen by restoring the the underlying image that was saved previously. +----------------+ | | | | +-----|-----+ | | B | | A | +-----|-----+ | | | +-----|-----+ | | C | | | +-----|-----+ | | | | | | | +----------------+ The image for Frame (C) is saved, and Frame (C) is erased from the screen by restoring the the underlying image that was saved previously. +----------------+ | | | | +-----|-----+ | | B | | A | +-----|-----+ | | | | | | | | | | | | | | | +----------------+ The image for Frame (B) is saved, and Frame (B) is erased from the screen by restoring the the underlying image that was saved previously. +----------------+ | | | | | | | A | | | | | | | | | Programmer's Reference Guide - 248 - TEGL Windows Toolkit APPENDICES | | | | | | | | +----------------+ The composite image of (A) is now complete and can be updated. The images (B), (C) and (D) are restored by reversing the above steps. In the earlier generations of TEGL, this formed the basis of the stacked frame concept (the removal of images that overlaps the current). Partial Image Update As you can imagine, this process is slow and causes a lot a of unnecessary updates to the screen. With the foundation of q a simple window manager, we can now begin to refine this process. Partial image update is removing only the intersection portion of the frames from the screen by extracting a section of the saved image. The following shows the intersection of D,C and B that is needed to be replaced on the screen. +--+ |D | | | +-----+ | | |B | | | +-----+ | | +-----+ | | |C | | | +-----+ +--+ Partial Image (D) is replaced first, followed by Partial (C) and (B). Refined Partial Image Update Since we are only interested in the composite image of (A), there is still a lot of unnecessary update to the screen. Imagine a notepad and you wish to write on the fifth page of the notepad. The fastest way to lift up five pages in a group, write, and close the notepad. So let's split image (D) into 5 pieces. +--+ |D1| Programmer's Reference Guide - 249 - TEGL Windows Toolkit APPENDICES +--+ +--+--+ |D2| B| +--+--+ +--+ |D3| +--+ +--+--+ |D4| C| +--+--+ +--+ |D5| +--+ Notice the double pages of (D2)(B) and (D4)(C). Now we only need to replace (D1), (B), (D3), (C) and (D5). We don't need to replace (D2) and (D4) because (B) and (C) has already restored the composite image of (A). TEGL was further refined to (cut out) only the pieces that needs to be replaced, thus removing all unnecessary updates to the screen. A Refined Partial Image Update Algorithm check for condition where by replacing the bottom image will replace the top image. eg. +----------------+ |1 +---------+ | | | 2 +-----+ | | | | 3 | | | +---+-----+ | +----------------+ Replacing 3 will be redundant, since we want to update 1, replacing 2 will remove both 2 and 3. check if we can begin trim the ends off one of the overlapped images to reduce the size that we need to replace. +---------+ +---------+ +---------+ +---------+ +---+---------+ +---------+---+ | +-----+ | +-----+ | +-----+ | | : | | | : | | : | | +---|.....| +-|.....|-+ |.....|---+ +---------+ | +---------+ +---------+ | | | | | | | | | | | | | | | | | | | +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +---+-----+ +-+-----+-+ +-----+---+ +---------+ | +---------+ +---------+ | | | | | | | | | | | | : | | | : | | : | | +---|.....| +-|.....|-+ |.....|---+ +---------+ | +---------+ +---------+ | Programmer's Reference Guide - 250 - TEGL Windows Toolkit APPENDICES | | | | | | +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ +-----+ | | | | | | | | | | | | +---------+ +---------+ | +---------+ +---|.....| +-|.....|-+ |.....|---+ | : | | : | | | : | | | | | | | | | | | +---------+ +---------+---+ +---------+ +---+-----+ +-+-----+-+ +-----+---+ +-----+ +-----+ +---------+ +-----+ +-----+ +-----+ | | +---------+ | : | | | | | | | | +---------+| : | +---------+ | | | | | | | | : |+---------+ | | +---|.....| +-|.....|-+ |.....|---+ +---+---------+ +-----+ +-----+ | +-----+ | +-----+ | +-----+ | +---------+ +---------+ +---------+ create an new insert that has one end trimmed and repeat steps 1 through 3 to cut the images into the necessary pieces. +-----+ +-----+ +-----+ +---------+ +-----+ +-----+ +---| | +-| |-+ | |---+ | : | +---------+ | | | | | | | | | | | | +---------+ | : | +---------+ +---|.....| +-|.....|-+ |.....|---+ | | +---------+ | : | +-----+ +-----+ +-----+ +-----+ +-----+ +---------+ +-----+-------+ +-------+-----+ +-----+ +-----+ | | | +-----+ +-----+ | | | +-------|.....| |.....|-------+ |.....|-------+ | | | | +-------|.....| | | | | | | | | +-------|.....| |.....|-------+ | | +-------| | | |-------+ +-----+ | | | | | | +-----+ +-----+ +-----+ +-------+-----+ +-----+-------+ +---------++-----++---------+ +---------+ +---------++-----++---------+ |.........|| ||.........|---+|.........|+---|.........|| ||.........| +---------+| |+---------+ |+---------+| +---------+| |+---------+ | ||.....|-------+| | | | | |+-------|.....|| | | |+-----+ || | | | | || +-----+| | +-----+ +---------++-----+ +-----+ +-----++---------+ +-----+ +-----+ +-----++---------+ +-----+ +---------++-----+ +-----+ | | | || +-----+ | | +-----+ || | | | | | | |+-------|.....| | | |.....|-------+| | | | +---------+| +---------+| |+---------+| |+---------+ |+---------+ |.........|+---|.........|| ||.........|| ||.........|---+|.........| +---------+ +---------++-----++---------++-----++---------+ +---------+ The only time that we are unable to split an overlapping image is when the image overlaps by 1 pixel. +---------+ | | +----------| |-----------+ | +----+---------+ | +---------------| |------+ | | Programmer's Reference Guide - 251 - TEGL Windows Toolkit APPENDICES +---------+ A Quick Run through the algorithm The procedure to handle the splitting of images is called StackOverlaps. StackOverlaps works in the following fashion: Top (Stackptr)* Bottom +--+---------+-----+---+ Top +----------------+ |D |x,y,x1,y1|image|...| +---------+--+ | +--+---------+-----+---+ | | | +--+---------+-----+---+ | |--+ | |C |x,y,x1,y1|image|...| | |B | A | +--+---------+-----+---+ | D |--+ | +--+---------+-----+---+ | | | |A |x,y,x1,y1|image|...| | |--+ | +--+---------+-----+---+ | |C | | +--+---------+-----+---+ | |--+ | |A |x,y,x1,y1|image|...| | | | +--+---------+-----+---+ +---------+--+ | Bottom | | +----------------+ PrepareForUpdate(A) creates temporary stack entries: Top (Stackptr)* +--+---------+-----+---+ +----> |B1|x,y,x1,y1|image|...| | +--+---------+-----+---+ | +--+---------+-----+---+ +----------------+ | +--> |C1|x,y,x1,y1|image|...| +---------+--+ | | | +--+---------+-----+---+ | |D1| | | | +--+---------+-----+---+ | +-----+ | | | +> |D1|x,y,x1,y1|image|...| | |B1 | A | | | | +--+---------+-----+---+ | D +-----+ | | | | +--+---------+-----+---+ | +-----+ | | | +> |D |x,y,x1,y1|image|...| | |C1 | | | | +--+---------+-----+---+ | +-----+ | | | +--+---------+-----+---+ | | | | | +--> |C |x,y,x1,y1|image|...| +---------+--+ | | +--+---------+-----+---+ | | | +--+---------+-----+---+ +----------------+ +----> |B |x,y,x1,y1|image|...| +--+---------+-----+---+ +--+---------+-----+---+ |A |x,y,x1,y1|image|...| +--+---------+-----+---+ Bottom Programmer's Reference Guide - 252 - TEGL Windows Toolkit APPENDICES Begin Cutting and Eliminating: Comparing only the overlapped images. +--+---------+-----+---+ +--+ +--+ +----> |B1|x,y,x1,y1|image|...| Bottom |D1| |D1| | +--+---------+-----+---+ Image | |--+ | | | +--+---------+-----+---+ | |B1| | | | +--> |C1|x,y,x1,y1|image|...| | |--+ | | | | +--+---------+-----+---+ | | | | | | +--+---------+-----+---+ | | | |--+ | | +> |D1|x,y,x1,y1|image|...| Top Image | | | |C1| | | | +--+---------+-----+---+ | | | |--+ | | | | +--+ +--+ StackOverlaps compares B1 with D1, B1 with C1 and C1 with D1 for overlaps. eliminate redundant overlaps Appendix B - Heap Management ___________________________________________________________________________ One of the major problems with window management is the amount of dynamic memory that is allocated and de-allocated. Memory is constantly fragmented with records, dynamic variables, and window images, thus reducing the largest block size over a period of time. Empty Heap Memory Fragmented Heap Memory Top of DOS Memory Top of DOS Memory FreePtr-> +-----------------+ +-----------------+ | * | |-----------------|1--+ | | FreePtr-> |-----------------|2--|+ | | | | || | | | Free Space | || | | | 60k | || | | HeapPtr-> |-----------------| || | * | |-----------------| || | cmaxavail | | | || | 341k | | Free Space | || Programmer's Reference Guide - 253 - TEGL Windows Toolkit APPENDICES | * | | 70k | || | | | | || | | |-----------------|2<-|+ | | |-----------------| | | | | Free Space | | | | | * | | | | | cmaxavail | | | | | 102k | | | | | * | | | * | | | | HeapPtr-> |-----------------| <-----HeapOrg-----> |-----------------|1<-+ | * Program * | | * Program * | This chapter will discuss how the TEGL heap manager using reservehugeminimum reduces the fragmentation that occurs. TEGL Heap Manager There are only two main pointers that manages the heap. The heapptr points to the end of the last memory block. freeptr points to a list of free memory blocks that can be re-used. Top of DOS Memory +-----------------+ |-----------------|1--+ FreePtr-> |-----------------|2--|+ | | || | Free Space | || | 60k | || HeapPtr-> |-----------------| || |-----------------| || | | || | Free Space | || | 70k | || | | || |-----------------|2<-|+ |-----------------| | | Free Space | | | * | | | cmaxavail | | | 102k | | | * | | | | | |-----------------|1<-+ | * Program * | When memory is requested from the TEGL Heap Manager, a sequential scan of the freeptr chain is made to see if any of the free memory space can be re-used. Any free space that satisfy the requested size will be used. Programmer's Reference Guide - 254 - TEGL Windows Toolkit APPENDICES The free space is then reduced by the allocation size and removed from the freeptr chain if the block is completely allocated. cgetmem(102k) Top of DOS Memory Top of DOS Memory +-----------------+ +-----------------+ |-----------------|1--+ FreePtr-> |-----------------|2--+ FreePtr-> |-----------------|2--|+ | | | | | || | | | | Free Space | || | Free Space | | | 60k | || | 60k | | HeapPtr-> |-----------------| || HeapPtr-> |-----------------| | |-----------------| || |-----------------| | | | || | | | | Free Space | || | Free Space | | | 70k | || | 70k | | | | || | | | |-----------------|2<-|+ |-----------------|2<-+ |-----------------| | |/////////////////| | Free Space | | |/////////////////| | * | | |/////////////////| | cmaxavail | | |/////////////////| | 102k | | |/////////////////| | * | | |/////////////////| | | | |/////////////////| |-----------------|1<-+ |-----------------| | * Program * | | * Program * | cgetmem(20k) Top of DOS Memory Top of DOS Memory +-----------------+ +-----------------+ |-----------------|1--+ |-----------------|1--+ FreePtr-> |-----------------|2--|+ FreePtr-> |-----------------|2--|+ | | || | | || | Free Space | || | Free Space | || | 60k | || | 60k | || HeapPtr-> |-----------------| || HeapPtr-> |-----------------| || |-----------------| || |-----------------| || | | || | Free Space | || | Free Space | || | 50k | || | 70k | || |-----------------|2<-|+ | | || |/////////////////| | |-----------------|2<-|+ |-----------------| | |-----------------| | |-----------------| | | Free Space | | | Free Space | | | * | | | * | | | cmaxavail | | | cmaxavail | | Programmer's Reference Guide - 255 - TEGL Windows Toolkit APPENDICES | 102k | | | 102k | | | * | | | * | | | | | | | | |-----------------|1<-+ |-----------------|1<-+ | * Program * | | * Program * | When memory is released (freed), the TEGL Heap Manager sequentially scans the freeptr chain to see if any of the free memory space is adjacent to the memory block that is being freed. cfreemem(A) Top of DOS Memory Top of DOS Memory +-----------------+ +-----------------+ |-----------------|1--+ |-----------------|1--+ |-----------------|2--|+ |--------x--------|2--|+ |--------x--------|3--||+ |-----------------|5--||--+ |-----------------|4--|||+ FreePtr-> |-----------------|4--||+ | FreePtr-> |-----------------|5--||||+ | * | ||| | | * | ||||| | | ||| | | | ||||| | | ||| | | | ||||| | | ||| | | | ||||| | | ||| | | * | ||||| | * | ||| | HeapPtr-> |-----------------| ||||| HeapPtr-> |-----------------| ||| | |+++++++++++++++++| ||||| |+++++++++++++++++| ||| | |+++++++++++++++++|2<-|+||| |+++++++++++++++++|2<-|+| | (A)>>>|+++++++++++++++++| | ||| | | | | | |+++++++++++++++++|3<-|-+|| (A)>>>|-----------------| | | | |+++++++++++++++++| | || |+++++++++++++++++| | | | |+++++++++++++++++|5<-|--|+ |+++++++++++++++++|5<-|-|-+ |+++++++++++++++++| | | |+++++++++++++++++| | | |+++++++++++++++++|1<-+ | |+++++++++++++++++|1<-+ | |+++++++++++++++++| | |+++++++++++++++++| | |+++++++++++++++++|4<----+ |+++++++++++++++++|4<---+ | * Program * | | * Program * | If adjacent memory is found, the free space pointer is removed from the freeptr chain and TEGL's heap manager takes the most recent entry and moves it to fill the now empty position. The size and the original pointer (A) is adjusted to reflect a new pointer position and size. Top of DOS Memory Top of DOS Memory +-----------------+ +-----------------+ |-----------------|1--+ |-----------------|1--+ |-----------------|4--|-+ |-----------------|4--|-+ FreePtr-> |-----------------|5--|-|+ |-----------------|5--|-|+ | * | | || FreePtr-> |-----------------|A--|+|| | | | || | | |||| Programmer's Reference Guide - 256 - TEGL Windows Toolkit APPENDICES | | | || | | |||| | | | || | | |||| | | | || | | |||| | | | || | | |||| | * | | || | * | |||| HeapPtr-> |-----------------| | || HeapPtr-> |-----------------| |||| |-----------------| | || |+++++++++++++++++| |||| | | | || ||||||||||||||||||| |||| | | | || ||||||||||||||||||| |||| (A)>>>|-----------------| | || |+++++++++++++++++|A<-|+|| |+++++++++++++++++| | || |+++++++++++++++++| | || |+++++++++++++++++|5<-|-|+ |+++++++++++++++++|5<-|-|+ |+++++++++++++++++| | | |+++++++++++++++++| | | |+++++++++++++++++|1<-+ | |+++++++++++++++++|1<-+ | |+++++++++++++++++| | |+++++++++++++++++| | |+++++++++++++++++|4<---+ |+++++++++++++++++|4<---+ | * Program * | | * Program * | When all possible adjacent blocks have been removed, the TEGL heap manager checks if the end of memory block is equal to the heapptr. If not, a free space entry is added to the bottom of freeptr. cfreemem(B) Top of DOS Memory Top of DOS Memory +-----------------+ +-----------------+ |-----------------|1--+ |-----------------|1--+ |-----------------|4--|-+ |-----------------|4--|-+ |-----------------|5--|-|+ FreePtr-> |-----------------|5--|-|+ FreePtr-> |--------x--------|A--|+|| | * | | || | * | |||| | | | || | | |||| | | | || | | |||| | | | || | | |||| | | | || | | |||| | | | || | * | |||| | | | || HeapPtr-> |-----------------| |||| | | | || (B)>>>|-----------------| |||| | | | || | | |||| | | | || | | |||| | * | | || |-----------------|A<-|+|| HeapPtr-> |-----------------| | || |+++++++++++++++++| | || |+++++++++++++++++| | || |+++++++++++++++++|5<-|-|+ |+++++++++++++++++|5<-|-|+ |+++++++++++++++++| | | |+++++++++++++++++| | | |+++++++++++++++++|1<-+ | |+++++++++++++++++|1<-+ | |+++++++++++++++++| | |+++++++++++++++++| | |+++++++++++++++++|4<---+ |+++++++++++++++++|4<---+ | * Program * | | * Program * | The TEGL memory manager sorts the free space entries, so that all Programmer's Reference Guide - 257 - TEGL Windows Toolkit APPENDICES allocation of space using cgetmem will always be towards the lower part of the heap memory. TEGL Upper Heap Manager The TEGL fgetmem is slightly different in its management methods. Allocation of memory is always attempted between heapptr and freeptr before searching for free space within the freeptr chain. fgetmem(20k) Before cgetmem fgetmem +-------+ +-------+ +-------+ |-------|1--+ |-------|1--+ |-------|1--+ FreePtr-> |-------|2--|+ FreePtr-> |-------|2--|+ FreePtr-> |-------|2--|+ | * | || | * | || | 40k | || | 60k | || | 60k | || |-------| || | * | || | * | || |///////| || HeapPtr-> |-------| || HeapPtr-> |-------| || HeapPtr-> |-------| || |-------| || |-------| || |-------| || | | || | * | || | | || | * | || | 50k | || | * | || | 70k | || |-------|2<-|+ | 70k | || | * | || |///////| | | * | || |-------|2<-|+ |-------| | |-------|2<-|+ |-------| | |-------| | |-------| | | | | | | | | | | | | | | | | | | | | * | | | * | | | * | | | 102k | | | 102k | | | 102k | | | * | | | * | | | * | | | | | | | | | | | |-------|1<-+ |-------|1<-+ |-------|1<-+ |Program| |Program| |Program| When memory is released (freed), fgetmem uses cfreemem to release the memory block back into the heap. cfreemem(A) Top of DOS Memory Top of DOS Memory +-----------------+ +-----------------+ |-----------------|1--+ |-----------------|1--+ |--------x--------|2--|+ |-----------------|3--|-+ |-----------------|3--||+ |-----------------|4--|-|+ |-----------------|4--|||+ FreePtr-> |-----------------|5--|-||+ FreePtr-> |-----------------|5--||||+ | * | | ||| | * | ||||| | | | ||| | | ||||| | | | ||| | | ||||| | | | ||| Programmer's Reference Guide - 258 - TEGL Windows Toolkit APPENDICES | | ||||| | | | ||| | * | ||||| | * | | ||| HeapPtr-> |-----------------| ||||| HeapPtr-> |-----------------| | ||| |+++++++++++++++++| ||||| |+++++++++++++++++| | ||| |+++++++++++++++++|1<-+|||| |+++++++++++++++++|1<-+ ||| (A)>>>|+++++++++++++++++| |||| | | ||| |+++++++++++++++++|2<--+||| (A)>>>|-----------------| ||| |+++++++++++++++++| ||| |+++++++++++++++++| ||| |+++++++++++++++++|3<---+|| |+++++++++++++++++|3<---+|| |+++++++++++++++++| || |+++++++++++++++++| || |+++++++++++++++++|4<----+| |+++++++++++++++++|4<----+| |+++++++++++++++++| | |+++++++++++++++++| | |+++++++++++++++++|5<-----+ |+++++++++++++++++|5<-----+ | * Program * | | * Program * | If adjacent memory is found, the free space pointer is removed from the FreePtr chain and TEGL's heap manager moves the free chain structure up by one entry to close the empty position. The size and the original pointer (A) is adjusted to reflect a new pointer position and size. Top of DOS Memory Top of DOS Memory +-----------------+ +-----------------+ |-----------------|3----+ |-----------------|A--+ |-----------------|4----|+ |-----------------|3--|-+ FreePtr-> |-----------------|5----||+ |-----------------|4--|-|+ | * | ||| FreePtr-> |-----------------|5--|-||+ | | ||| | | | ||| | | ||| | | | ||| | | ||| | | | ||| | | ||| | | | ||| | | ||| | | | ||| | * | ||| | * | | ||| HeapPtr-> |-----------------| ||| HeapPtr-> |-----------------| | ||| |-----------------| ||| |+++++++++++++++++| | ||| | | ||| ||||||||||||||||||| | ||| | | ||| ||||||||||||||||||| | ||| (A)>>>|-----------------| ||| |+++++++++++++++++|A<-+ ||| |+++++++++++++++++| ||| |+++++++++++++++++| ||| |+++++++++++++++++|3<---+|| |+++++++++++++++++|3<---+|| |+++++++++++++++++| || |+++++++++++++++++| || |+++++++++++++++++|4<----+| |+++++++++++++++++|4<----+| |+++++++++++++++++| | |+++++++++++++++++| | |+++++++++++++++++|5<-----+ |+++++++++++++++++|5<-----+ | * Program * | | * Program * | When all possible adjacent blocks have been removed, the TEGL heap manager checks if the end of memory block is equal to the HeapPtr. If not, a free space entry is added to the bottom of FreePtr. cfreemem(B) Programmer's Reference Guide - 259 - TEGL Windows Toolkit APPENDICES Top of DOS Memory Top of DOS Memory +-----------------+ +-----------------+ |-----------------|A--+ |-----------------|3----+ |-----------------|3--|-+ |-----------------|4----|+ |-----------------|4--|-|+ FreePtr-> |-----------------|5----||+ FreePtr-> |--------x--------|5--|-||+ | * | ||| | * | | ||| | | ||| | | | ||| | | ||| | | | ||| | | ||| | | | ||| | | ||| | | | ||| | | ||| | * | | ||| | | ||| HeapPtr-> |-----------------| | ||| | | ||| (B)>>>|-----------------| | ||| | | ||| | | | ||| | | ||| | | | ||| | * | ||| |-----------------|A<-+ ||| HeapPtr-> |-----------------| ||| |+++++++++++++++++| ||| |+++++++++++++++++| ||| |+++++++++++++++++|3<---+|| |+++++++++++++++++|3<---+|| |+++++++++++++++++| || |+++++++++++++++++| || |+++++++++++++++++|4<----+| |+++++++++++++++++|4<----+| |+++++++++++++++++| | |+++++++++++++++++| | |+++++++++++++++++|5<-----+ |+++++++++++++++++|5<-----+ | * Program * | | * Program * | TEGL uses the more efficient method of maintaining the free space chain in sorted order. This allows allocation of memory to favor the lower portion of the heap. This does not remove the fragmentation problem where one non-movable records is allocated in the middle of the heap. Combining the best of both Heap Managers (Coexisting) What we noted that we needed was the ability to have two heaps. One for miscellaneous dyanamic variables and one for large allocations for images. Combined with the virtual memory handler, this allows the paging out the large allocations effectively releasing adjacent memory. At the same time we did not want to limit either heap. The lower heap must have the ability to flow over to the second heap without problems. ReserveHugeMinimum provides an elegant solution of partitioning the standard heap into two parts. A single non-movable byte is allocated as a partitioner. cgetmem fgetmem +-------+ +-------+ +-------+ FreePtr-> |-------|1--+ FreePtr-> |-------|1--+ FreePtr-> |-------|1--+ | | | | | | | | | | | | | | | | | | Programmer's Reference Guide - 260 - TEGL Windows Toolkit APPENDICES | | | | | | | | | | | | | | | | | | | 329k | | | 329k | | | 200k | | | | | | | | | | | | | | | | | HeapPtr-> |-------| | | | | | | | |///////| | | | | | | | |///////| | |HugeMin| | |HugeMin| | |///////| | HeapPtr-> |-------| | HeapPtr-> |-------| | |-------| | | | | | | | | | | | | | | | | | | | | 12k | | | 11k | | | 11k | | | | | | | | | | | | | | | | | | | | | | | |-------|1<-+ |-------|1<-+ | | | |///////| |///////| |-------|1<-+ |-------| |-------| |Program| |Program| |Program| cgetmem will always search for free space through the FreePtr Chain, the lower partitioned area will always be used first (it is always the first few entries in the freeptr chain). fgetmem used by the window manager will always attempt to allocate space between heapptr and freeptr before searching through the free space pointer chain. Even when searching through the free space chain, a comparison is made on the minimum area for allocating. When TEGL frees a memory block, the free space pointer is sorted upwards into the free space chain. Top of DOS Memory +-----------------+ +--A|-----------------| +|--B|-----------------| +||--C|-----------------| +|||--D|-----------------| +||||--E|-----------------| ||||| |-----------------|4--+ ||||| |-----------------|1--|+ ||||| |-----------------|3--||+ ||||| |-----------------|2--|||+ ||||| |-----------------|5--||||+ ||||| | | ||||| ||||+->A|+++++++++++++++++| ||||| |||+-->B|+++++++++++++++++| ||||| ||+--->C|+++++++++++++++++| ||||| |+---->D|+++++++++++++++++| ||||| +----->E|+++++++++++++++++| ||||| | Hugemin | ||||| |-----------------| ||||| Programmer's Reference Guide - 261 - TEGL Windows Toolkit APPENDICES |+++++++++++++++++|2<-|+||| |+++++++++++++++++|3<-|-+|| |+++++++++++++++++|5<-|--|+ |+++++++++++++++++|4<-+ | |+++++++++++++++++|2<----+ | * Program * | Programmer's Reference Guide - 262 - TEGL Windows Toolkit Conditional Compilation The file teglcond.h contains conditions compilation directives that support different facilities with the Toolkit. Note! If you change any defines you will have to make the entire toolkit. The following defines affect the Toolkit: #define NOGR - The toolkit is built with no explicit references to graphics.lib provided with Turbo C. Instead a compatible module tgraph is used which provides a subset of the functions provided in graphics.lib If your application does not need all the features of the Graph unit then compiling with this directive enabled can save as much as 25K of code size in a program (assuming the BGI drivers are linked in). #define NOVIRT - The code that implements virtual memory using either EMS or a disk drive is not included. Applications save about 8K of code space but can easily run out of memory if many windows are opened. This is more critical for EGA or VGA displays since the windows require four times as much memory than CGA or Hurcules displays. #define QUICKC - The toolkit will be built assuming that a Microsoft C compiler is being used. #define TURBOC - The toolkit will be built assuming that the Turbo C compiler is being used. Programmer's Reference Guide - 263 - TEGL Windows Toolkit INDEX Bar menu................................................... 94 Bar........................................................237 Click and drag............................................. 24 EGA........................................................144 Event driven code.......................................... 23 Expand and shrink.......................................... 25 FGAND...................................................... 77 FGNORN..................................................... 77 FGNOT...................................................... 77 FGOR....................................................... 77 FGXOR...................................................... 77 FontTable..................................................192 Jagged..................................................... 97 Keyboard events............................................ 25 Mickey.....................................................124 MoveFromVirtual procedure..................................223 MsSense.................................................... 84 MxClick.................................................... 84 OE......................................................... 96 OM......................................................... 95 Option entry............................................... 96 Option menu................................................ 95 Proportional...............................................192 ReadKey.................................................... 91 TEGLSupervisor............................................. 24 Timer ticks................................................ 25 VGA........................................................139 abort_msg..................................................149 activebutton............................................... 30 addcapturekey..............................................131 addframe...................................................184 allocateexpandedmemorypages................................205 animate....................................................186 animatecomplete............................................186 animateinit................................................185 asksoundsense..............................................197 beep.......................................................198 bigimagesize...............................................143 cfreemem...................................................203 cga640x200x2...............................................136 cgetmem....................................................202 checkctrlbreak.............................................233 checkctrlbreakfs...........................................233 checkformouseselect........................................173 checkmouseclickpos.........................................172 clearbuttoninfo............................................121 clearkeyboardbuf........................................... 90 clearteglkeyboardbuf....................................... 90 clearteglscreen............................................151 closegraph.................................................238 Programmer's Reference Guide - 264 - TEGL Windows Toolkit INDEX cmaxavail..................................................225 collapsetoiconshow.........................................165 collapsetomsclick..........................................166 coltox..................................................... 31 commitupdate............................................... 61 countframes................................................ 49 createbarmenu..............................................105 createimagebuffer.......................................... 74 createoptionmenu........................................... 96 createshadowom............................................. 98 currentframenumber.........................................185 cursorshape................................................117 deallocateexpandedmemorypages..............................207 definebuttonclick..........................................163 defineglobalkeyclickarea................................... 91 definelocalkeyclickarea.................................... 92 definelongbuttonclick......................................164 definemouseclickarea....................................... 84 defineoptionclickarea......................................110 defineoptions.............................................. 97 defineresizeclickarea......................................228 defineresizeminmax.........................................229 definesliderarea...........................................229 defineuserbuttonclick......................................164 deletecapturekey...........................................132 destination................................................181 detectgraph................................................238 drawlongbutton.............................................170 dropimagebuffer............................................ 75 dropkeyclick............................................... 92 dropsliders................................................230 dropstackimage............................................. 54 droptimercount.............................................129 droptimertick..............................................234 easytegl................................................... 36 editstring.................................................196 ega640x350x16..............................................137 emminstalled...............................................204 emsblockread...............................................215 emsblockwrite..............................................214 emsclose...................................................216 emsopen....................................................213 emspagesavailable..........................................205 emsseek....................................................214 errmess.................................................... 31 explodefromiconhide........................................166 explodefrommsclick.........................................167 extendtextxy...............................................162 extractimg.................................................146 extractpixs................................................146 Programmer's Reference Guide - 265 - TEGL Windows Toolkit INDEX fastline...................................................140 findframe..................................................171 findkeyclickptr............................................ 93 findmouseclickptr.......................................... 85 findsliderfs...............................................230 fitframe................................................... 32 flipapage..................................................144 flipvpage..................................................145 fmttegltextxy..............................................189 fontname...................................................193 frameexist................................................. 49 framefromicon.............................................. 32 frameselectandmove......................................... 63 frametext.................................................. 33 freeimagebuffer............................................ 77 freevirtual................................................224 freezemouse................................................123 frozenmouse................................................122 getbiti....................................................142 getbkcolor.................................................238 getbuttonpressinfo.........................................121 getbuttonreleaseinfo.......................................120 getcolor...................................................239 getfillpattern.............................................239 getfrontimage.............................................. 78 getfsimage................................................. 76 getgraphmode...............................................240 gethandlecountused.........................................208 getkbsteps.................................................127 getmaxx....................................................240 getmaxy....................................................240 getmousesensitivity........................................125 getmousey.................................................. 34 getorigin..................................................180 getpageframebaseaddress....................................206 getpagesownedbyhandle......................................209 getpartialfrontimage....................................... 78 getpixs....................................................141 gettextsettings............................................241 getversionnumber...........................................207 getyesno................................................... 35 graphresult................................................241 herc720x348x2..............................................137 hideimage.................................................. 56 hidemouse..................................................116 imagesize..................................................241 initgraph..................................................242 keystackptr................................................ 93 lastcol.................................................... 36 lastrow.................................................... 37 Programmer's Reference Guide - 266 - TEGL Windows Toolkit INDEX line.......................................................242 linkfs..................................................... 72 linkunderfs................................................ 73 lockimage.................................................. 79 mapexpandedmemorypages.....................................206 mcursoroff.................................................114 mcursoron..................................................115 mouseposition..............................................119 movebox....................................................167 moveframe.................................................. 70 movestackimage............................................. 68 movetovirtual..............................................224 msclick.................................................... 24 msetpos....................................................115 mssense.................................................... 24 nilkeycallproc.............................................133 nilunitproc................................................234 origin procedure...........................................180 outbaroption...............................................106 outframetextxy............................................. 38 outtegltextxy..............................................189 outtextxy..................................................243 overlaparea................................................235 overlayimg.................................................147 pageinfs................................................... 79 pageoutfs.................................................. 80 pageoutimagestack.......................................... 81 pictsize...................................................149 popimage................................................... 51 prepareforpartialupdate.................................... 58 prepareforupdate........................................... 60 pressbutton................................................174 pushimage.................................................. 50 putbiti....................................................142 putfsimage................................................. 76 putpict.................................................... 45 putpict....................................................149 putpixs....................................................141 putuserbuttonclick.........................................165 quickframe................................................. 39 quit....................................................... 38 rectangle..................................................243 replaceoptiontext..........................................102 reservehugeminimum.........................................227 resetframe.................................................182 resetkeyclickcallproc...................................... 93 resetmouseclicks........................................... 88 resetmsclickactive......................................... 87 resetmsclickcallproc....................................... 87 resetmsclicksense.......................................... 89 Programmer's Reference Guide - 267 - TEGL Windows Toolkit INDEX resetoptionmenuevents......................................111 resetsequence..............................................183 resettimerflag.............................................129 resizeframe................................................231 resizeoptionmenu........................................... 99 restorecrtmode.............................................243 restoretext................................................ 39 rotatestackimage........................................... 52 rotateunderstackimage...................................... 53 rowtoy..................................................... 40 selectafile................................................195 selectandmoveframe.........................................232 selecteasytext............................................. 40 sequence...................................................182 setapage...................................................143 setautorotate.............................................. 64 setbarbordercolor..........................................108 setbarborderoff............................................108 setbarfillstyle............................................109 setbarmenucolor............................................107 setbarmenumargin...........................................109 setbarshadowtext...........................................108 setbartextcolor............................................107 setbkcolor.................................................244 setcolor...................................................244 seteasyfont................................................ 41 setfillpattern.............................................244 setfillstyle...............................................245 setframemobility........................................... 66 sethidesubmenu.............................................104 setimagecoordinates........................................ 81 setkbsteps.................................................126 setkeyboardmouse...........................................125 setmousecolor..............................................119 setmousehotspot............................................119 setmouseminmax.............................................122 setmouseposition...........................................116 setmousesense..............................................197 setmousesensitivity........................................124 setmoveframecallproc....................................... 67 setmoverestrictions........................................ 65 setoptionmenubordercolor...................................104 setoptionmenucolors........................................103 setproportional............................................192 setshadowbordercolor.......................................157 setshadowcolor.............................................156 setshadowfillpattern.......................................157 setshadowfillstyle.........................................158 setshadowtexthighlight.....................................161 setshadowtextshadow........................................160 Programmer's Reference Guide - 268 - TEGL Windows Toolkit INDEX setshadowtexttype..........................................160 setshiftkeys...............................................134 setslideposition...........................................232 setteglbackcolor...........................................152 setteglbordercolor.........................................153 setteglbordershow..........................................152 setteglfillpattern procedure...............................154 setteglfillstyle...........................................154 setteglfont................................................192 settextjustify.............................................245 settimerstart..............................................128 settimertick...............................................235 setvideochoices............................................138 setvpage...................................................144 shadowbox..................................................155 shadowboxtext..............................................156 shadowtext.................................................159 shadowtexthighlightoff.....................................161 shifttextxy................................................162 showbuttonstatus...........................................134 showcoordinates............................................ 58 showfonts..................................................193 showimage.................................................. 57 showmouse..................................................116 showonefont................................................193 slidebeep..................................................198 soundswitch................................................199 spawn......................................................113 super vga..................................................138 svga800x600x16.............................................138 swapbytes..................................................147 swapteglintroff............................................113 swapteglintron.............................................114 swaptimerin................................................128 swaptimerout...............................................127 teglcharheight.............................................191 teglcharwidth..............................................191 teglkeypressed.............................................133 teglreadkey................................................132 teglsupervisor............................................. 19 tegltextwidth..............................................190 teglwrtchar................................................191 timerswtich................................................129 togglecheckmark............................................100 toggleentrystatus..........................................101 toggleoptionbar............................................103 unfreezemouse..............................................124 unlinkfs................................................... 70 unlockimage................................................ 82 unuseimage................................................. 82 Programmer's Reference Guide - 269 - TEGL Windows Toolkit INDEX useharddisk................................................223 useimage................................................... 83 vdskcloseheapfile..........................................221 vdskfreemem................................................219 vdskgetmem.................................................219 vdskopenheapfile...........................................217 vdskreadheapdata...........................................221 vdskwriteheapdata..........................................220 vemsopenheapfile...........................................218 vga640x480x16..............................................138 videoautodetect............................................139 videoid....................................................139 videopage..................................................145 vidid......................................................136 virtualmemused.............................................225 visualbuttonpress..........................................175 xorbox.....................................................148 xorcornerbox...............................................148 zipfrombox.................................................169 ziptobox...................................................168